Java

Steven's Guide to Writing Quality Javadoc

Steven Benitez

Apr 5, 2017 • 2 min read

Whether you're building an application or a shared library, writing quality Javadoc is an important and sometimes difficult task. What follows are my thoughts on writing quality Javadoc.

Write for Both Source Code and Web Consumption

Many developers read Javadoc in source code within their IDE, rather than consult an external Javadoc website. Your documentation should be readable in source as well as on the web. To that end, wrap Javadoc at the 80 character margin to keep it readable in source code without horizontal scrolling.

A Javadoc block should consist of a description of one or more sentences, properly capitalized, and with proper punctuation, followed by tags in alphabetical order.

Unlike descriptions, values for @param and @return tags should not start with a capital letter or end with punctuation.

/**
 * An effective trap for capturing delicious, tasty roadrunners.
 *
 * @author Wile E. Coyote
 */
public class RoadrunnerTrap {}

For descriptions which span multiple paragraphs, add a <p> tag at the start of each subsequent paragraph rather than between paragraphs. This preserves the readability when viewing Javadoc in source code.

Don't Repeat Yourself

Not bothering to write any Javadoc is bad, but writing verbose Javadoc that doesn't add value or applying redundant Javadoc to trivial methods is downright awful. Don't pollute your code with bad documentation.

When in doubt, leave it out. — Joshua Bloch

Suggested Practices

The @author tag should include a person's proper name. Some IDEs will generate this tag on classes along with a user's username, such as @author stevenb. Update your IDE to include your proper name or drop this tag.
If the value of a @param tag is obvious or just repeats the name of the param, then omit the tag.
If the description of your method indicates that it returns a value, such as for a method named getCustomers(), then omit the @return tag which would likely just repeat what you've already said.
The @throws tag should document both checked and unchecked exceptions thrown by a non-trivial method. Don't use @exception which is an alias to @throws.
Use {@link} tags when referencing other types in descriptions. If you refer to a type several times in a description, consider using {@code} tags in subsequent references.
Use @see to reference related types which are not explicitly called out in a description using {@link}.
Consider using @since for APIs or tracking when features were added to an application.

Peer Review

In addition to reviewing code with team members, you should also be reviewing Javadoc to make sure that documentation is clear and accurate.

Learn From Others

There is a wealth of open source Java libraries available. Take a look at the JDK Javadoc as well as projects like Google Guava.