Javadoc
Hello! In this article, i will discuss javadocs as well as some tips on writing javadocs.
JavaDocs
Javadoc is a documentation generation system, which reads comments in the source and generates compiled documentation in the form of HTML5.
Why use javadocs?
- Improved understanding of the general structure of the project
- help coworkers understand the complicated code
- easy to generate
How to write a javadocs
With the help of Intellij, you could easily just type /** and press enter:
/**
Intellij just auto-generates the javadocs comments like this:
/**
*
*
*
*/
If you have a return type, parameters, and throw exceptions, IntelliJ also auto-generates for you.
/**
* Returns a newly generated id
* @param a
* @return a generated id
* @throws Exception
*/
public Long example(Long a) throws Exception {
newId += 1;
return newId;
}
In the beginning, it is best to describe what the method returns. You could understand a lot if you understand what returns.
This method is fairly simple, but imagine a complicated, legacy method in which there are many parameters and returns unreadable numbers. It will save a lot of time for developers if you have a javadocs that explains what the method does and returns.
advice for writing javadocs
- The goal is to understand the code within a few seconds
- The javadocs class must explain the goal and responsibilities
- The javadocs method must explain parameters and what it returns
- do not include explanations for implementations
- briefly explain what exception is thrown
- Try to avoid any comments inside the code
Conclusion
In this post, i included what a javadocs is and some tips on writing javadocs.