...
Table of Contents maxLevel 3
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).
Code Block | ||
---|---|---|
| ||
/**
* 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 | ||
Code Block | ||
| ||
/** * 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); } |
...
Code Block | ||
---|---|---|
| ||
/** * 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
Interfaces and classes
Naming
...