Page History

...

Exceeding the maximum line-length of 120 characters will fail the build.

Comments 

Javadoc Comments

Javadocs are used to document the APIs of 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 number of Javadoc conventions that come up frequently need to be addressed in reviews frequently:

...

Other Comments

• Internal comments ( // or /* ... */ ) are encouraged to provide additional context to the reader, where the nuances may not be discerned from the code alone.
• Avoid adding comments that provide no additional information, for example:
  • // sets the parent value on the node
  • node.setParent(parent);
.
• Descriptions of interfaces/classes/enums should start with a noun, e.g. "Representation of..." and avoid starting with "This class...." .
• Descriptions of constructors should start with a passive verb, e.g. "Creates..." and avoid starting with "This constructor..." or "Constructor", or "Default constructor"; they should be sentences and therefore be capitalized and punctuated properly.
  
• Descriptions of methods should start with a passive verb, e.g. "Returns...", "Adds...", "Computes...", and avoid starting with "This method..."; as with constructor descriptions, they should be sentences and therefore be capitalized and punctuated properly.
  
• Note that the first sentence of the method description will be used in the generated "Method Summary" section of the documentation page, and thus should be a one-sentence summary of what the method does (see example below).
• Since javadoc text is parsed as HTML:
  •  the use of <p> (but not <p></p> or <p/>) should be used to mark paragraph breaks
  • <pre> ... </pre> can be used for blocks of monospaced text (e.g. example code fragments)
  • <ul><li> ... </li>... </ul> constructs can be used to list bullet points
• "@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.
• The description text for @param should a simple reminder to the reader as to what the parameter is; any detail about constraints or assumptions of parameters should be described in the method description.
• Similarly, the text for the @return (for non-void methods) should be a simple summary of what is returned.
• 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.

• Note that parameter types and return types should not be referenced with @link pragmas in the method description as the javadoc compiler will automatically provide hyperlinks to those entities in the constructed documentation page (see example below).

/**
 * Representation of something with "foo" behavior.
 * <p>
 * This is Javadoc commenting for classes and interfaces.
 * Javadoc descriptions are full sentences using English prose.
 */
public interface Foo {
 
    /**
     * Returns true if the given parameter is within tolerance of the sample.
     * <p>
     * Additional detail about what the method does, and maybe constraints
     * or assumptions about input parameters should be provided in the 
     * method description here.
     *
     * @param param functions that take arguments have this
     * @return methods that return a value should indicate this
     */
    boolean sampleMethod(Integer param);
} 
 

...