Page History

...

Indentation and spaces

• Four spaces, NOT a tab character, are used for regular indentation. For code broken into multiple lines, eight spaces are used indent lines after the firstA blank line should separate method declarations:

  Code Block
  language java
  if (obj instanceof DefaultDevice) { return Objects.equals(this.id, other.id) && ... // end of previous method } Objects.equals(this.type, other.type) && Objects.equals(this.manufacturer, other.manufacturer);<-- blank line here /** * ... javadoc description */ public void someMethod() { ...

  
  

• Four spaces, NOT a tab character, are used for regular indentation. For code broken into multiple lines, eight spaces are used indent lines after the first:If the line has to break at the dot separator ".", the dot symbol should be at the beginning of the next line:
   

  Code Block
  language java
  publicif void describeTo(Description description(obj instanceof DefaultDevice) { return descriptionObjects.appendText("status '")equals(this.id, other.id) && Objects.appendText(status.getDescription())equals(this.type, other.type) && .appendText("'"); }

• Trailing whitespaces should be removed in both code and comments.

• Objects.equals(this.manufacturer, other.manufacturer);

  
  

• If the line has to break at an operator (such as "&&" in the example above), the operator should be at the end of the previous line.

   

• If the line has to break at the dot separator "." (method invocation), the dot symbol should be at the beginning of the next line: There should be a space between keywords (if, for, catch, etc.), parenthesis, and braces, as well as when casting:

  Code Block
  language java
  ifpublic void describeTo(timer != nullDescription description) { try { description.appendText("status '") DeviceId did = (DeviceId) elementId; .appendText(status.getDescription()) ... } catch (IOException e) { ....appendText("'"); }

  
  

• Trailing whitespaces should be removed in both code and comments.

• There should be a space between keywords (if, for, catch, etc.), parenthesis, and braces, as well as when castingThere should be a space before the curly braces in method definitions. Arguments are not padded (neither in definition nor invocation):
  

  Code Block
  language java
  public Deviceif getDevice(DeviceId deviceIdtimer != null) { try { DeviceId did return= store.getDevice(deviceIdDeviceId) elementId; ... }

The project uses Checkstyle  to enforce some of the formatting mentioned above. Violations will prevent the build from succeeding.

Line Length

• catch (IOException e) { ...

• There should be a space before the curly braces in method definitions. Arguments are not padded (neither in definition nor invocation):

  Code Block
  language java
  public Device getDevice(DeviceId deviceId) { return store.getDevice(deviceId); }

The project uses Checkstyle  to enforce some of the formatting mentioned above. Violations will prevent the build from succeeding.

Line Length

Recommended line-length limit is 80 Recommended line-length limit is 80 characters, but it is understood if lines occasionally spill over this limit for aesthetic reasons. Chronic trespasses of the 80 character line-length boundary may fail the review.

...

• 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 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.
  
• "@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.

• 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

/**
 * This is Javadoc commenting for classes and interfaces.
 * Javadoc descriptions are full sentences.
 */
public interface Foo {
 
    /**
     * or Thisassumptions about isinput theparameters formatshould forbe Javadocsprovided forin publicthe methods
     * andmethod those defined by interfacesdescription here.
     *
     * @param param functions that take arguments have this
     * @return methods that return a value should indicate this
     */
    boolean sampleMethod(Integer param);
} 
 

...

/**
 * Implementing classes should have Javadocs as well, to emphasize 
 * their function.
 */
public class FooImpl implements Foo {
	
	/**
     * Important variables and structures should also be 
     * commented so that it is picked up by Javadocs.
     */
	private static final int SAMPLE = 5;

    @Override
    public boolean sampleMethod(int param) {
        // classic one-liner
        boolean val = false;
        /*
         * Multi-line comments within the code may use this 
         * convention.
         */
        if (param < SAMPLE) {
            // FIXME: multiple lines may be commented like this
            // for code that may be removed or changed
            // return true;  
            val = true;
        }
        return val;
    }	
} 

Sample Javadoc generated documentation page

Image Added

Interfaces and classes

Naming 

...