Code Conventions

Following the lead of well established projects such as Apache and Eclipse, all code in CAS will comply with the Code Conventions for the Java and additionally with the CAS specific conventions listed below. Javadoc should exist on all publicly exported class members [Bloch, 2001] and follow the How to Write Doc Comments for the Javadoc Tool style guide.

CAS Specific Code Conventions

Brackets

All brackets should appear in compact form and are mandatory even for single line statements.

public class FooClass {
    public void barMethod() {
        if (...) {
            // single line statement
        }
    }
}

Needless else clauses

We do not use needless else clauses. We would write:

public class FooClass {
    public String barMethod() {
        if (...) {
            return "foo";
        }
        
        return bar;

    }
}

rather than

public class FooClass {
    public String barMethod() {
        if (...) {
            return "foo";
        } else {
            return "foobar";
        }
    }
}

Indentations

Code indentation should be set to use 4 spaces. Tabs should never be used for indentation.

Static Members

Static member variables will always be in uppercase wherein each word is separated by an underscore:

private static String SOME_OBJECT = "TheObject";

Logging

We use SLF4J for logging. In abstract classes, the provided logger should be mark as protected so that it can be reused in subclasses. In the case where we create our own Log instance, we will use the recommended practice of declaring logger objects by SLF4j:

package some.package;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
      
public final class MyClass {
  private final [static] Logger LOGGER = LoggerFactory.getLogger(MyClass.class);
  ... etc
}
...
public class MyClass {
  private final Logger logger = LoggerFactory.getLogger(this.getClass());
  ... etc
}

Parameterized log messages are preferred:

SLF4J parameterized log messages

Object entry = new SomeObject();
log.debug("The entry is {}.", entry);

This is the preferred method over checking for a particular logging level and concatenating parameters through String objects.

Qualifying instance variables with "this"

We qualify all instance variables with "this" with the exception of the Logging instances. We don't qualify that variable with "this" because it is well-known to be threadsafe. logger.warn("Message") becomes more idiom than invocation of instance variable.

Use of the final keyword.

We use the keyword "final" wherever we can, because it is probably a good idea.

Naming testcases

If we were writing a JUnit testcase for code defined in Foo.java, we would name it FooTests.java . We do not allow any code which is not a testcase to have a name ending in "Tests". All testcase must use annotations (@Test) instead of extending junit.framework.TestCase. Furthermore, the usage of "junit.framework" classes is generally discouraged.

Injection

For required dependencies, the "contructor way" of injection must be used where as setters can be used for optional dependencies.

equals() and hash() methods

The recommend way to build the hash() and equals() methods is to use the EqualsBuilder and HashCodeBuilder classes form the commons-lang(3) jar.

Code Conventions