Java Coding Conventions

Recommended reading: Java For Small Teams.

Code Style

We mainly follow Google's Java style guide.

Key Points

Formatting:

• Spaces, not tabs.
• Block indentation is 2 spaces.
• K&R style
• Braces are not optional

Example:

public String doSomething(String str, Iterator itr) throws Exception {

  if (str == null) {
    complain("str is null!");
  } else {
    System.out.println(str);
  }
  while (itr.hasNext()) {
    String val = (String)itr.next();
    System.out.println(val);
  }
  return "Done!";
}

Not Optional: Make sure you put braces ({}) around all conditionals (i.e. if, else, while, for, etc.), no matter how short. This makes it much harder to make any scoping mistakes.

Naming Conventions:

• For class names, use upper camel case.
• For method and variable names, use lower camel case.
• In class and method names, acronyms and contractions should only have the first letter capitalized (eg. Db, Kb, Url). This is in keeping with the camel casing convention.
• Longer, more descriptive names are better than short cryptic names.
• Public static final variables should be in all caps.
• One variable per declaration (e.g. no int a, b;)

Import order:

1. java imports
2. javax imports
3. all non-static imports, in ASCII order
4. blank line
5. all static imports

Annotating Source Code

Use Checker Framework's @Nullable/@NonNull annotations directly in the source.

Logging

Internally, we use SLF4J for all our logging needs. This, however, is just an interface. The actual logging implementation we use is Logback.

Documentation

All code should be documented, and you should use proper Javadoc formatting. If in doubt, consult the Javadoc Website.