Code Style Guidelines

To maintain a level of quality in the codebase, the project maintains a set of coding and testing guidelines.

Indentation and spaces

• Four spaces, NOT tabs, are used for indentation.
• 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 casting:
  

  if (timer != null) {
      try {
          DeviceId did = (DeviceId) elementId;
          ...
      } catch (IOException e) {
  ...

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

  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.

Comments 

Javadocs are used to document the codebase itself. Interfaces are heavily documented with Javadocs so that implementing methods (annotated with @Override) inherit the commenting. 

/**
 * 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
     */
    public boolean sampleMethod(Integer param);
} 
 

At the time of this writing, various formats are used within the code. 

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

Interfaces and classes

• Naming. 
  Interfaces should always be given first pick of clear names that convey their purpose.  For example, if there is an interface representing a network device, and a class implementing it, the interface should be given the name Device, and the class, something indicating that it implements the Device interface, e.g. DefaultDevice.
  
  
• Referencing.
  Wherever possible, references should be made to the interface, and not the implementing class. This includes method parameters. 
  
  
• Nested classes.
  A class that implements functions specific to a particular class (e.g. its event handlers or services that it exports) should be implemented as an inner private class within the class. Such classes have names beginning with Internal-, e,g InternalClusterEventListener. 
  
  
• Data types.
  Wherever possible, use a rich data type over a primitive (e.g. MACAddress versus a long). This reduces ambiguity.

Logging

The codebase uses SLF4J for logging. DO NOT use System.out.*. 

The logger should be private final, and associated with the particular class:

private final Logger log = getLogger(getClass());