Item 44: Write doc comments for all exposed API elements

1.  If an API is to be usable, it must be documented.

 

2.  Javadoc generates API documentation automatically from source code with specially formatted documentation comments, more commonly known as doc comments.

 

3.  To document your API properly, you must precede every exported class, interface, constructor, method, and field declaration with a doc comment. If a class is serializable, you should also document its serialized form.

 

4.  To write maintainable code, you should also write doc comments for most unexported classes, interfaces, constructors, methods, and fields. 

 

5.  The doc comment for a method should describe succinctly the contract between the method and its client. With the exception of methods in classes designed for inheritance, the contract should say what the method does rather than how it does its job. 

 

6.  The doc comment should enumerate all of the method’s preconditions, which are the things that have to be true in order for a client to invoke it, and its postconditions, which are the things that will be true after the invocation has completed successfully. Typically, preconditions are described implicitly by the @throws tags for unchecked exceptions; each unchecked exception corresponds to a precondition violation. Also, preconditions can be specified along with the affected parameters in their @param tags.

 

7.  In addition to preconditions and postconditions, methods should document any side effects. A side effect is an observable change in the state of the system that is not obviously required in order to achieve the postcondition.

 

8.  Finally, documentation comments should describe the thread safety of a class or method.

 

9.  To describe a method’s contract fully, the doc comment should have an @param tag for every parameter, an @return tag unless the method has a void return type, and an @throws tag for every exception thrown by the method, whether checked or unchecked.

 

10.  By convention, the text following an @param tag or @return tag should be a noun phrase describing the value represented by the parameter or return value. The text following an @throws tag should consist of the word “if,” followed by a clause describing the conditions under which the exception is thrown.

 

11.  The Javadoc utility translates doc comments into HTML, and arbitrary HTML elements in doc comments end up in the resulting HTML document.

 

12.  The use of the Javadoc {@code} tag around the code fragment causes the code fragment to be rendered in code font, and it suppresses processing of HTML markup and nested Javadoc tags in the code fragment. To include a multiline code example in a doc comment, use a Javadoc {@code} tag wrapped inside an HTML <pre> tag:

<pre>{@code and follow it with the characters }</pre>

 

13.  {@literal} tag, which suppress processing of HTML markup and nested Javadoc tags. It is like the {@code} tag, except that it doesn’t render the text in code font.

 

14.  The first “sentence” of each doc comment becomes the summary description of the element to which the comment pertains. The summary description ends at the first period that is followed by a space, tab, or line terminator (or at the first block tag). The best solution is to surround the offending period and any associated text with a {@literal} tag, so the period is no longer followed by a space in the source code.

 

15.  When documenting a generic type or method, be sure to document all type parameters.

 

16.  When documenting an enum type, be sure to document the constants as well as the type and any public methods.

 

17.  When documenting an annotation type, be sure to document any members as well as the type itself. Document members with noun phrases, as if they were fields.

 

18.As of release 1.5, package-level doc comments should be placed in a file called package-info.java instead of package.html.

 

19.The definitive guide to writing doc comments is Oracle’s How to Write Doc Comments: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html