The art of Javadoc

Every so often I browse the Spring framework API documentation to learn a little more about the art of documenting an API. There’s Javadoc, and then there’s Javadoc. Much of the Javadoc I’ve written or read falls into describing what’s already right in front of the reader. Over time I’ve come to realize that good Javadoc has to tell readers the things they’d otherwise have to tease out of the code.

Here’s what you typically have to look for between the lines.

• How to obtain the object
• How to configure it
• What dependencies it has
• How to change its behavior
• How it relates to other entities

I appreciate it when Javadoc links to outside information that helps explain an implementation detail or the approach taken. Examples of how to use the API are invaluable, too. Writing Javadoc at this level of detail is painstaking, of course, and keeping it up to date as the API changes is harder still.

For fun, try opening ten classes at random in your current project and score their Javadoc from 0 to 10 using these criteria.

• The class has no Javadoc (0 points)
• The class’s Javadoc is outdated or misleading
• The class’s Javadoc is very brief
• Even a newcomer can tell what the class is for from its Javadoc
• The class’s Javadoc goes further and offers additional information (10 points)

Results

• 0–20 points. You’re probably writing self-documenting code.
• 21–40 points. Besides writing self-documenting code, you drop an irrelevant remark into the documentation here and there.
• 41–60 points. There’s a visible attempt to document things. The classes have some documentation at least.
• 61–80 points. The Javadoc for your classes holds up to closer scrutiny.
• 81–100 points. Congratulations. It looks like you’ve reached documentation heaven.