Coding style guidelines

This document is a work-in-progress and as such does not contain a complete list of guidelines, nor are they in any order. Some of them may need further clarification.

• Use simple English for naming. This includes but is not limited to:

  • don't use a complicated word when a simpler equivalent exists (e.g. start > initialise)
  • don't add words that state the obvious
  • when naming methods, try to only describe what is does, not its possible uses

• When creating a variable for time, always specify the unit in the name (e.g. timeSeconds, timeMillis etc). This way we do not risk confusion. This goes for methods that return a time as well. For methods that accept time parameters, it is preferred to use two variables - one for time, another for unit (e.g. java.util.concurrent.TimeUnit). An exception to this rule is if the value is encapsulated in a class that handles units for us, such as java.time.Duration.

• We use static imports wherever reasonable. We consider it reasonable when the signature of the method is sufficiently descriptive by itself (e.g. java.nio.file.Files.readAllBytes), but make exceptions when it is very vague (e.g. java.nio.file.Paths.get).

• We do not use the asterisk import (e.g. import static foo.bar.MyClass.*). This is to avoid writing misleading or confusing code.

• A unit test should make sense when read in isolation. As such, any values that are going to be tested in the assertions should be kept literal. Furthermore these same values should appear in the set-up of the test (referring to the top of the test method, not the general 'setUp' method that sometimes appears in test classes).

• We DO NOT yet have a convention for how to make code (particularly test code) multiplatform without creating clutter when dealing with paths or new-line characters. This needs to be decided.

• Put public methods above private ones. This allows us to quickly find the "entry points" into a class without scrolling through implementation details.

• When using fluent interfaces, call each method on a separate line, except in cases where it is very simple, e.g. passing in a single variable.

• When processing multiple items, e.g. in an array or list, use the Java streaming API in cases where the index of the items being processed is not relevant.

• As part of a general principle against clutter, avoid the final modifier except for fields and classes.