Javadoc Comments – Moving the Documentation in with the Code

TIP: References Quick List

Having a wiki or other document with designs for the change is always good. However, they can quickly become outdated and even their presence can become part of the easily lost tribal knowledge of a team, which may erode as the team changes over time.

I have also seen teams lose old design docs as the larger company changes vendor direction, moving from one storage system to another, where:

Pieces are missed in the migrated,
Team changes over time meaning that:
- Access is slowly lost, or
- Memories that the documents even exist slowly erodes.

It is worth investing time in good, complete Javadoc comments that will grow and change as the code does…and be easily accessible as new team members examine the code. Granted, while this doesn’t solve all documentation needs…it helps move the needle forward when familiarizing yourself with new code.

How do we make a good Javadoc comment, though? What is required and what syntax (format) should we use?

You may remember from our earlier post, that Javadoc comments go before the thing they describe, start with /** and end with */ . Next, there is a description for the thing (field, method, class, or package) we are documenting. After that, come some tags, with their own comments. Some of the commonly used tags within a Javadoc comment are:

Label	Supported For	Format	Notes
@author	Class, Interface	`@author <authorName>`	Optional. Can be repeated multiple times, if desired, for multiple authors. Version history in an SCM can also be used to determine file author(s).
@deprecated	Package, Class, Interface, Method, Constructor, Field.	`@deprecated As of <version>, replaced by <replacement>` `@deprecated as of <version>, no replacement.`	When code is deprecated, it means it is on the path to retirement. It should no longer be used and instead the replacement should be used, so you are not impacted when it is eventually retired/sunset.
@exception	Method, Constructor	`@exception <ClassName> <Description>`	Recommended when any checked exception (or unchecked exception that the calling code may want to handle) is thrown from a method / constructor. See also: @throws. Multiple @exception tags are allowed, for different exceptions.
@param	Method, Constructor	`@param <parameterName> <parameterDescription>`	A description for a single input parameter to a method. Repeat for each input parameter used in the method.
@return	Method	`@return <returnValueDescription>`	Describes the value that will be returned during happy-path scenarios.
@see	Any	`@see` `<a href="endpoint">label</a>` `@see` `package.class#member` `label`	Adds a link to either other Javadoc documentation or an external endpoint.
@since	Any	`@since <freeFormText>`	Optional. Indicates when a particular bit of code was added to the larger code base. Multiple since tags are allowed, if desired.
@throws	Method, Constructor	`@throws <ClassName> <Description>`	Recommended when any checked exception (or unchecked exception that the calling code may want to handle) is thrown from a method / constructor. See also: @exception Multiple @throws tags are allowed, for different exceptions.
@version	Class, Interface	`@version <versionNumber>`	I saw this used more when CSV (file-specific SCM) was popular. When using SVN or Git, which version all files in the repo together, I haven’t seen this used as frequently. Instead, the artifact’s overall version is tracked as a whole and tags are often added to the repo, so that we can easily track the state of all of the files in that version of the artifact(s).

Example Method Javadoc

/**
 * Add two short values.
 *
 * @param shortValue1 The first value to add.
 * @param shortValue2 The second value to add.
 * @return An int value representing the two values added together.
 */
public static int add(final short shortValue1, final short shortValue2) ...

Example Generated Javadoc Documentation

The Apache StringUtils documentation is an example of generated Javadoc pages/documentation.