# JavaDocs When writing good software, it’s essential to write good documentation as well. For that reason, there should be a collection of guidelines and best practices agreed upon on the company level for writing good and concise code documentation based upon reliable sources. In short, JavaDoc is a document generator tool in Java programming language for generating documentation in HTML format. Every JavaDoc comment must include the following: ``` /** Comment /* ``` {% hint style="info" %} All of the comments are removed at compile time so it doesn’t affect the performance of the execution. {% endhint %} ## Good practices JavaDoc should be defined at the company or team level to ensure consistency and coherence in documentation practices. Here are some of the good practices:


Use standard JavDoc tags	Include standard block and inline tags like: `@param`, `@return`, `@throws`, `@see`, `@since` , `{@link}` and`@deprecated` to describe parameters, return values, exceptions, and deprecated methods respectively.
Be descriptive, clear and concise	Write clear and concise descriptions for methods, classes, fields, and parameters. Explain what they do and their significance.
Adhere to naming conventions	By using meaningful names for methods, classes, and variables, ensuring that their purpose is clear from the name itself, we can avoid writing redundant comments that clutter the code.
Use HTML markup sparingly	Use HTML markup (such as `<code>`, `<ul>`, `<li>`, etc.) when necessary to format text for better readability. But keep it minimal and use it only when needed.
Include example usage	Add code snippets or examples to demonstrate how to use a method or class.
Update JavaDocs regularly	As you change code, update the JavaDocs regularly. Outdated comments can lead to confusion.
Document edge cases and specifics	Mention any edge cases, restrictions, or constraints that might affect the behaviour of the method or class.
Document thread safety and performance	Describe if methods or classes are thread-safe and mention any performance considerations or complexities.
Use inline comments when necessary	For complex logic or sections that might not be clear from the JavaDoc alone, use inline comments within the code to provide additional context.
Review and maintain consistency	Consistency in style, formatting, and level of detail across the codebase is crucial for better readability and understanding. Conduct regular reviews to ensure adherence to Javadoc standards.