Page History

...

• Internal comments ( // or /* ... */ ) are encouraged to provide additional context to the reader, where the nuances may not be discerned from the code alone.
• Avoid adding comments that provide no additional information, for example:
  • // sets the parent value on the node
  • node.setParent(parent);
• Avoid adding comments at the end of a statement; place them above the line concerned.

/**
 * 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
     * or assumptions about input parameters should be provided in the 
     * method description here.
     *
     * @param param functions that take arguments have this
     * @return methods that return a value should indicate this
     */
    boolean sampleMethod(Integer param);
} 
 

...

Variables and parameters should not be gratuitously decorated with the final keyword. ; (This is an out-dated convention from Java 1.1 era). Let the Java compiler do its work of optimizing the code for you.

...

...

Otherwise, let the Java compiler/optimizer to its work. The final keyword  keyword should also be used to on class declarations to make objects of the class immutable.prevent classes from being extended. For example, utility classes or collections of constants.

On a related note, even though method parameters are not decorated with final, they should still be treated as final; it is considered bad coding practice to modify a parameter within the method. The same behavior can always be achieved with local variables.

public void badExample(SomeType type, SomeValue value) {
    if (value == null) {
        value = SomeValue.DEFAULT_VALUE;
    }
    ...
 
 
public void goodExample(SomeType type, SomeValue value) {
    SomeValue v = value != null ? value : SomeValue.DEFAULT_VALUE;
    ...

Naming

• JSON fields should be in camel case:

  Code Block
  { "aliasIp": "10.1.2.3" }

  and not "alias_ip".

...