Javadoc Best Practice

Table of Contents

• What to Comment
• The summary fragment
• Where to Write Javadoc
• Javadoc for class
• Params
• throws
• Overriding
• Use minimal HTML tags, not valid XHTML
• [@link and @code](https://blog.joda.org/2012/11/javadoc-coding-standards.html)
• More Elements
• Deprecated
• More Javadoc Annotations
• Misc Tips about Javadoc
• Common Mistake when Write Javadoc

What to Comment

• Document Why, not just“What

The summary fragment

• use the third person form
• end with period.
• describe what the method does, not how it does it
• put implementation comments in the body

This is a fragment—a noun phrase or verb phrase, not a complete sentence. It does not begin with A {@code Foo} is a..., or This method returns..., nor does it form a complete imperative sentence like Save the record.. However, the fragment is capitalized and punctuated as if it were a complete sentence.

Tip: A common mistake is to write simple Javadoc in the form /** @return the customer ID */. This is incorrect, and should be changed to /** Returns the customer ID. */.

Where to Write Javadoc

• for every public non-test class, and every public or protected member of such a class

Javadoc for class

• ImmutableSet > A {@link Set} whose contents will never change, with many other important properties detailed at
• {@link ImmutableCollection}.

Util class

• what the members of the class are and what may have in the future
• Futures > Static utility methods pertaining to the {@link Future} interface.

Params

• Treat @param and @return as a phrase
  • They should start with a lower case letter, typically using the word “the”.
  • They should not end with a dot.
• No need to document all params.
• The @param entries should be specified in the same order as the parameters.
• Use @param document type parameters when really needed: @param <T>
• If null is accepted, make sure it’s clear what happens in that case.
  • which may be null.

@param elements the {@code Iterable} to add to the {@code ImmutableList}

throws

• Treat @throws as an if clause
• Futures.getDone(Future future)

* @throws ExecutionException if the {@code Future} failed with an exception
* @throws CancellationException if the {@code Future} was cancelled
* @throws IllegalStateException if the {@code Future} is not done

Overriding

• On implementation class when there is nothing to add

/** Implementation of {@link THE_INTERFACE} */

• when want to add something:

/**
 * {@inheritDoc}
 *
 * <p>Additional paragraphs…
 */

Use minimal HTML tags, not valid XHTML

• omit optional closing tags (</p>, </li>),
• just <p>, not <p></p> or </p>

[@link and @code](https://blog.joda.org/2012/11/javadoc-coding-standards.html)

• {@link} allows the IDE to provide a click-able link and to update it when Refactor > Rename is used.
• {@link} shows warning when there is a typo.
• Link to a class named ‘Foo’: {@link Foo}.
• Link to a method ‘bar’ on a class named ‘Foo’: {@link Foo#bar}.
• Link to a method ‘baz’ on this class: {@link #baz}.
• Link specifying text of the hyperlink after a space: {@link Foo the Foo class}.
• Link to a method handling method overload {@link Foo#bar(String,int)}.
• Do not use @code for null, true or false
• Don’t use <code> or <tt>, or @see
• Use {@code Set} instances instead of {@code Set}s

More Elements

<b>Note:</b>
<b>Warning:</b>
<b>Performance note:</b>
“Implementation:

Deprecated

/**
 * ....
 * @deprecated
 * Explain why it's deprecated and what to use instead..
 */
@Deprecated

More Javadoc Annotations

• @apiNote, @implSpec and @implNote
• @author

Misc Tips about Javadoc

• javadoc should be before Annotation.
• put TODO comment out of the Javadoc since callers don’t need to know about.

Common Mistake when Write Javadoc

• missing javadoc for non-private methods in non-test class
• not using the 3rd person
• not needed/redundant
• typo
• error caused by copy/paste
• there should be trailing period in summary, no trailing period in params, returns and throws.
• forget to update javadoc after change code logic or signature
• extra asterisk in javadoc.
• extra terminating period in @parmas or @returns, @throws.