Page History

...

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 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.

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

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. 

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

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

...

When adding logs for debugging, rather than using info or warn, use the debug or trace verbosity level and set the log level in Karaf to inspect the debug messages. 

Usage of Guava (More of a tools section topic)

...

• Checking for null method inputs - using checkNotNull(): 

  Code Block
  language java
  import static com.google.common.base.Preconditions.checkNotNull; ... @Override public void removeDevice(DeviceId deviceId) { checkNotNull(deviceId, DEVICE_ID_NULL); DeviceEvent event = store.removeDevice(deviceId); if (event != null) { log.info("Device {} administratively removed", deviceId); post(event); } }

• toString() - ToStringHelper():

  Code Block
  language java
  import static com.google.common.base.MoreObjects.toStringHelper; ... @Override public String toString() { return toStringHelper(this) .add("id", id) .add("vlan", vlan) .add("ipAddresses", ips) .toString(); }

• Data structures such as Lists, ImmutableSet, and HashMultiMap

• Unit testing - EqualsTester():

  Code Block
  language java
  import com.google.common.testing.EqualsTester; ... VlanId vlan1 = VlanId.vlanId((short) -1); VlanId vlan2 = VlanId.vlanId((short) 100); VlanId vlan3 = VlanId.vlanId((short) 100);   // first two equality groups contain equal objects, last differs // from constituents of first two groups new EqualsTester().addEqualityGroup(VlanId.vlanId(), vlan1) .addEqualityGroup(vlan2, vlan3) .addEqualityGroup(VlanId.vlanId((short) 10));

Imports

Import statements are expected to be organized by the IDE. It is understood that different IDEs use a slightly different scheme for organization. Settings for both Eclipse and IntelliJ IDEA are available to minimize (but not quite eliminate) these discrepancies.

Duplicate and unnecessary imports will result in build failure.

...

Home : Contributing to the ONOS Codebase

...