<qhelp>

<overview>

A public method or constructor that does not have a Javadoc comment makes an API more difficult to understand and maintain.

</overview> <recommendation>

Public methods and constructors should be documented to make an API usable. For the purpose of code maintainability, it is also advisable to document non-public methods and constructors.

The Javadoc comment should describe what the method or constructor does rather than how, to allow for any potential implementation change that is invisible to users of an API. It should include the following:

- A description of any preconditions or postconditions
- Javadoc tag elements that describe any parameters, return value, and thrown exceptions
- Any other important aspects such as side-effects and thread safety

Documentation for users of an API should be written using the standard Javadoc format. This can be accessed conveniently by users of an API from within standard IDEs, and can be transformed automatically into HTML format.

</recommendation> <example>

The following example shows a good Javadoc comment, which clearly explains what the method does, its parameter, return value, and thrown exception.

</example> <references>

- J. Bloch, Effective Java (second edition), Item 44. Addison-Wesley, 2008.
- Help - Eclipse Platform: Java Compiler Javadoc Preferences.
- Java SE Documentation: How to Write Doc Comments for the Javadoc Tool, Requirements for Writing Java API Specifications.
</references> </qhelp>