Page History

...

All public / protected / package-private entities must have javadoc comments; remember this is the documentation for the entity's API.
private entities do not need to have javadoc comments, but if they do, the comments should be properly formatted and complete.
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.
Class Descriptions
- Descriptions of interfaces / classes / enums should start with a noun, and describe what the entity embodies.
- For example "Representation of...", "Aggregation of...".
- Avoid starting with "This class....", or "This interface..." etc. as it is obvious from the context, and the phrase is redundant.
- Unit tests classes should also have a class description.
  - but methods within do not need to have javadoc comments, (although it is not discouraged)
Enum Constant Descriptions
- Not only should the enum as a whole be documented, but each constant (which is also public) should be documented.
- Typically a single line format is used, for example, for SortDirection.ASC you might have:
  - /** Designates ascending sort order. */
Constructor Descriptions
- Descriptions of constructors should start with a passive verb, e.g. "Creates..." or "Constructs..."
- Avoid starting the description with "This constructor..." or "Constructor", or "Default constructor"
- The first sentence of the description should be a complete, high level summary of what is constructed.
- Note that the first sentence of the constructor (or method) description is used in the generated "Method Summary" section of the documentation page; (see example below)
- Any additional sentences should provide the reader with further detail as needed.
- The description text should be written as prose, and therefore be capitalized and punctuated properly.
- The direct use of type names or variable names should be avoided where possible; for example:
  - rather than "Constructs a StructureHolder for the given WidgetElement."
  - it would be better to write "Constructs a structure holder for the given widget element."
Method Descriptions
- Descriptions of methods should start with a passive verb, e.g. "Returns...", "Adds...", "Computes..."
- Avoid starting the description with "This method..."
- Further sentences should provide additional details (in prose) as needed, typically referring to the method parameters and the return value (if any).
- The description should include details of special circumstances, for example, if and when null might be returned instead of a value type.
- Note that parameter / return types should not be referenced with @link pragmas in the method description; the javadoc compiler will automatically provide hyperlinks to those entities in the constructed documentation page (see example below).

Parameters and Return Value Descriptions
- There should be a blank line between the method description and the first @param clause.
- There should be a @param clause for each parameter to the method.
- There should be a @return clause if the method is declared as returning anything other than void.
- As a general guide, the reader should get a good sense of what the method does and what the parameters are, from reading just the method description alone.
- The description of the parameter / return value should simply remind the reader what the parameter / value is; the details of which they have already read in the method description.
- The description (sentence fragment) should start with lower case and not end with a period (.); for example:
  - @param id the entity identifier
  - @return the corresponding entity; or null if no such entity exists
  - @return true, if the key exists; false otherwise
Thrown Exception Descriptions
- Documentation should always be provided (with a @throws clause) for each type of exception thrown by the method (both checked and unchecked exceptions).
- Remember, only checked exceptions should be part of the method signature; unchecked exceptions should be omitted.
- For example:
  - @throws IllegalArgumentException if the provided value is out of bounds
  - @throws IllegalStateException if the context has not been initialized
- Note that these descriptions are short and to the point. If more detail is required about when or why the exceptions might be thrown, include it in the method description text.
Javadoc comments are parsed as HTML
- Whitespace is ignored, so use <p> (but not <p></p> or <p/>) 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 for bulleted lists.

For more information, see How to Write Doc Comments for the Javadoc Tool.

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);
Avoid adding comments at the end of a statement; place them above the line concerned.

Code Block

language	java

Code Block

language	java

/**
 * 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);
}

...

Variables and parameters should not be gratuitously decorated with the final keyword. ; (This is an out-dated convention from Java 1.1 era). Let the Java compiler do its work of optimizing the code for you.

The

...

exception to this "rule" is when the parameter is used as part of an anonymous class closure

...

defined within the method.

Otherwise, let the Java compiler/optimizer to its work. The final keyword keyword should also be used to on class declarations to make objects of the class immutable.prevent classes from being extended. For example, utility classes or collections of constants.

On a related note, even though method parameters are not decorated with final, they should still be treated as final; it is considered bad coding practice to modify a parameter within the method. The same behavior can always be achieved with local variables.

Code Block

public void badExample(SomeType type, SomeValue value) {
    if (value == null) {
        value = SomeValue.DEFAULT_VALUE;
    }
    ...
 
 
public void goodExample(SomeType type, SomeValue value) {
    SomeValue v = value != null ? value : SomeValue.DEFAULT_VALUE;
    ...

Naming

JSON fields should be in camel case:
Code Block
{ "aliasIp": "10.1.2.3" }
and not "alias_ip".

...

Page tree

Versions Compared

Old Version 25

New Version Current

Key

Other Comments

Naming