Javadoc Comments for Contracts

Javadoc comments (the ones enclosed in /** ...​ */) are exclusively used on classes, interfaces, fields, and methods and are placed directly above them. Here is an example from Map::size:

/**
 * Returns the number of key-value mappings in this map. If the
 * map contains more than Integer.MAX_VALUE elements, returns
 * Integer.MAX_VALUE.
 *
 * @return the number of key-value mappings in this map
 */
int size();

The example demonstrates syntax as well as semantics: a Javadoc comment is a contract. It promises API users what they can expect while keeping the type’s central abstraction intact by not talking about implementation details. At the same time, it binds implementers to provide the specified behavior.

Java 8 relaxed this strictness a little while formalizing different interpretations by introducing the (nonstandardized) tags @apiNote, @implSpec, and @implNote.  The prefixes, api or impl, specify whether the comment addresses users or implementers. The suffixes, Spec or Note, clarify whether this is actually a specification or only for illustration. Notice how @apiSpec is missing? That’s because the comment’s untagged text is supposed to fulfill that role: specifying the API.

Block Comments for Context

Block comments are enclosed in /* ...​ */. There are no restrictions on where to put them, and tools usually ignore them. A common way to use them is at the beginning of a class or even a method to give insights into its implementation. These can be technical details but can also outline the context in which the code was created (the famous why from code tells you what, comments tell you why) or paths not taken. A good example for providing implementation details can be found in HashMap, which starts like this:

/*
 * Implementation notes.
 *
 * This map usually acts as a binned (bucketed) hash table,
 * but when bins get too large, they are transformed into bins
 * of TreeNodes, each structured similarly to those in
 * java.util.TreeMap.
 * [...]
 */

As a rule of thumb, when your first solution isn’t your last, when you make a trade-off, or when a weird requirement or a dependency’s awkward API shapes your code, consider documenting that context. Your colleagues and your future self will thank you. (Silently.)

Line Comments for Weird Things

Line comments start with a //, which must be repeated on every line. There are no restrictions on where to use them, but it is common to put them above the commented line or block (as opposed to at the end). Tools ignore them—many developers do as well. Line comments are often used to narrate what the code does, which has rightfully been identified as a bad practice in general. It can still be helpful in specific cases, such as where the code has to use arcane language features or is easy to break in a subtle way (concurrency is the prime example for this).

Last Words

• Make sure to pick the right kind of comment.

• Don’t break expectations.

• Comment your &#!*@$ code!