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.

Template for commit messages

Short (50 chars or less) summary of changes.

More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together.

Further paragraphs come after blank lines.

Bullet points are okay, too
Typically a hyphen or asterisk is used for the bullet, preceded by a single space, with blank lines in between.

The summary should contain both a Jira issue number where possible and a brief description, e.g.

Sample Message

CAS-31415: Upgrade JDK source version to Java 9. 
 
Upgrading to JDK version 9 in order to solve a number of problems with the code.

Placing _both_ the issue number and brief description would improve commit history in SCM. The old practice where the Jira number exclusively is on the first line makes it hard to follow commit history in a pull request and other situations.

Central Authentication Service