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 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:
- Trailing whitespaces should be removed in both code and comments.
There should be a space between keywords (
,etc.), parenthesis, and braces, as well as when casting:
There should be a space before the curly braces in method definitions. Arguments are not padded (neither in definition nor invocation):
The project uses Checkstyle to enforce some of the formatting mentioned above. Violations will prevent the build from succeeding.
Javadocs are used to document the codebase itself. Interfaces are heavily documented with Javadocs so that implementing methods (annotated with
@Override) inherit the commenting.
At the time of this writing, various formats are used within the code.
Interfaces and classes
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.
Wherever possible, references should be made to the interface, and not the implementing class. This includes method parameters.
Nested (Inner) 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
Objects and Methods
Wherever possible, use a rich data type over a primitive (e.g.
MACAddress versus a
long). This reduces ambiguity.
- Classes that are intended to be instantiated as immutable objects (e.g.
DefaultDevice) should have class all variables declared
Maps, etc) returned by getters should be immutable, or a copy of the existing Collection.
synchronized(this)and synchronized methods wherever possible.
Opt for thread-safe objects such as
ConcurrentMap, and if using
synchronized, apply it to the structure that must be locked:
Additionally, some structures such as Hazelcast's
IMaphave per-key locks.
equals() and hashCode()
Any objects that are compared, or stored in any hash based data structure (e.g. HashSet, HashMap), should implement these methods. For objects that implement them, comparisons should use their
equals() method, and not
==. An exception to this rule are Enums.
JSON fields should be in camel case:
The codebase uses SLF4J for logging. DO NOT use
The logger should be private final, and associated with the particular class:
When adding logs for debugging, rather than using
warn, use the
trace verbosity level and set the log level in Karaf to inspect the debug messages.
Usage of Guava (More of a tools section topic)
ONOS leverages guava in several areas. Some prominent areas are:
Checking for null method inputs - using checkNotNull():
toString() - ToStringHelper():
- Data structures such as
Unit testing - EqualsTester():