Table of contents

The GDS Way and its content is intended for internal use by the GDS community.

Java style guide

The purpose of this style guide is to provide some conventions for working on Java code within GDS. The old Sun/Oracle Java style guide, the more recent Google Java style guide and the more far-reaching Java for Small Teams book are useful starting points.

Generally IntelliJ IDEA is used within GDS and consistency of its use helps when pairing and mob programming.

We favour consistency across our code, so when considering using a new or different method or paradigm to what exists already, ensure that you have agreement of your team.

Code formatting

Variable and field names should match the class they are instantiating, or have a descriptive name in the context of their use.

Always use curly braces around the body of an if statement, even if it’s only a single line.

Use the GDS Way EditorConfig file, which has settings for things like code indentation. Place a copy of this file named .editorconfig in the root of your project to have IntelliJ IDEA and some other editors automatically apply the settings. If your editor does not support EditorConfig, manually configure its settings to match.

Dependency injection (DI)

Consider whether dependency injection is appropriate for your project before using it. Some programmes use the Guice dependency injection framework.

Imports

No wildcard imports should be used. IntelliJ can be configured to explicitly import all classes and static methods in Preferences → Editor → Code Style → Java → Imports with “Class count to use import with *” and “Names count to use static import with *” both set to a very high number e.g. 1000.

The IntelliJ “Optimize Imports” command sorts imports and removes any that are unused. Before committing some changes, you can select all the classes in the modified files pane and then use this command to fix the imports for just the classes you modified.

Prefer functionality in the Java standard library

Where possible, use functionality from the Java standard library rather than external libraries.

Be mindful that improvements to the Java standard library mean that some external libraries that were popular in the past now add less value. For example, while Joda-Time was significantly better than the date and time libraries built in to older Java versions, the java.time package introduced in Java 8 renders it redundant. Similarly, Google’s Guava is very useful (and recommended) but the unmodifiable collections built in to Java 9 largely obviate the need for Guava’s immutable collections.

When using external libraries, favour those that play nicely with the Java standard library. For example, be wary of any library that introduces a new type that replicates the functionality of an existing type in the Java standard library without implementing the same interfaces (e.g. a list type that does not implement java.util.List).

Testing

Use JUnit for unit tests (it can also be used for many integration tests). For new projects, use the latest JUnit 5. It’s probably not worth migrating existing projects from JUnit 4 to JUnit 5 while JUnit 4 is still supported.

Use Mockito for mocking.

Code checking

The use of static analysis is encouraged. Static analysis tools for Java include SonarQube, Codacy, FindBugs and CheckStyle. However, be aware that such tools can detect an overwhelming number of problems if applied to an existing project, which tends to result in their checks being ignored.

Try to minimise compiler warnings. If you cannot remove a warning, use an appropriate annotation to suppress it, preferably with a comment explaining why. For example:

public void frobulateFoos() {
    LOGGER.info("Frobulating foos");

    // LibFoo returns a raw list but every element is always a Foo
    @SuppressWarnings("unchecked")
    List<Foo> foos = (List<Foo>) fooService.getFoos();

    foos.forEach(foo -> foo.frobulate());
}

Build tools

Either Gradle or Maven should be used as the build tool.

Web frameworks

We use Dropwizard as our web framework of choice.

Dropwizard has built-in support for validating requests with Hibernate Validator. Use Dropwizard’s validation in preference to rolling your own except in cases where Dropwizard’s built-in functionality cannot meet your validation requirements.

If you are sending logs to a service that requires them in a specific format, you may find our dropwizard-logstash logging extension useful.

JDK

The Oracle JDK is no longer free for production use. OpenJDK remains free to use (under the GPLv2 with the Classpath Exception) but Oracle only provide general-availability OpenJDK builds for the latest release.

The AdoptOpenJDK project (backed by big names including IBM and Microsoft) provides fully open-source pre-built OpenJDK binaries. For LTS releases (such as Java 8 and Java 11), AdoptOpenJDK have committed to releasing free updates for several years.

In addition, AdoptOpenJDK has niceties such as being available in package repositories, having friendly installers for desktop use, and offering ready-made Docker images containing OpenJDK.

This page was last reviewed on 10 May 2019. It needs to be reviewed again on 10 November 2019 by the page owner #gds-way .
This page was set to be reviewed before 10 November 2019 by the page owner #gds-way. This might mean the content is out of date.