Page History

...

Javadocs are used to document the codebase itself. Interfaces are heavily documented with Javadocs so that implementing methods (annotated with @Override) inherit the commenting.  Clarity of comments is important and therefore it is important to pay attention to detail and try to write concise, yet meaningful and clear comments.

Here are a few specific Javadoc conventions that come up in reviews frequently:

• All public/protected/package entities must have javadoc comments
• Descriptions of interfaces/classes/enums should start with a noun, e.g. "Representation of..." and avoid starting with "This class...." 
• Descriptions of methods should start with a passive verb, e.g. "Returns...", "Adds..." and avoid starting with "This method..."; they should be sentences and therefore be capitalized and punctuated properly.
  
• "@param name description" should be specified on the same line and wrap as needed from there; there should not be a line break between name and description
  
• Unit tests classes should also have class javadoc comment; methods within do not need to have javadoc comments, although it is not discouraged.
• Acronyms in comments should be properly capitalized, e.g. YANG, NETCONF, SNMP.

• Descriptions should avoid gratuitous capitalization and should avoid referencing class-names unless part of a @link pragma.

/**
 * This is Javadoc commenting for classes and interfaces.
 * Javadoc descriptions are full sentences.
 */
public interface Foo {
 
    /**
     * This is the format for Javadocs for public methods
     * and those defined by interfaces.
     *
     * @param param functions that take arguments have this
     * @return methods that return a value should indicate this
     */
    boolean sampleMethod(Integer param);
} 
 

...

Wherever possible, use a rich data type over a primitive (e.g. MACAddressMacAddress versus a long). This reduces ambiguity.

...