Practical Google style

Configuration files and practical tips and tricks to configure your Java project so as to apply (a slightly modified version of) the Google Java Style Guide.

This repository provides a Checkstyle configuration file; instructions for configuring your (Maven) POM (see below); and an Eclipse formatter configuration file together with some related instructions.

You might also be interested in these style guidelines.

Maven

Add the plugin maven-checkstyle-plugin to your POM, configured as in here, in order to fail your build in case of bad formatting. (If put directly into the build / plugins element instead of the pluginManagement element, the check will run by default during the verify phase.)

Checkstyle configuration file

The Checkstyle configuration file provided here is a modified version of their configuration file for Google Style Guide.

Modifications

I initially imported the Checkstyle (from the Checkstyle resources), then modified the file manually.

• braceAdjustment disabled because also applies to braces at the start of a line and after an end of statement, which I do not want.

• Put the global severity level at the Checkstyle default (error, instead of warning which was explicitly set in the original google checks configuration file), because I consider that the build should fail in case of style error.

  • I have however set most of the Javadoc related modules to warning severity. The Google Style Guide requires those checks, but I do not want those to break my build: while developing, I do not insist on having complete and nicely formatted Javadoc, which can be a loss of time when we are still unsure about the definitive form of an API. However, these warnings are relevant when aiming at publishing an API.

• Essentially disabled SummaryJavadoc. I kept “forbiddenSummaryFragments” but rendered the summary existence check ineffective with a trick by considering “space” as an end-of-sentence period. As configured originally, this does not correctly implement Google’s requirements, which requests the summary sentence only for public types. I replaced this with JavadocStyle, which allows for scope configuration and also checks that Javadoc effectively is there.

• Required a space after a record name and before the record elements (note that this is not covered in the Google Java Style Guide).

• Included SuppressWarningsFilter (and SuppressWarningsHolder) to permit suppressing checkstyle warnings with @SuppressWarnings annotations.

• Allowed one-letter abbreviations: one letter words such as X (the X Window System or the social network) or C (the programming language), lead to the perfectly valid (per GJSG) names XKey or CCompiler (though disagreement exists). Similarly, the name theHLetter complies with the GJSG. The Checkstyle default configuration forbids all of this. The modification tolerates all one-letter abbreviations (equivalently, consider that all one-letter words exist). This also requires to allow for the second letter to be uppercase when using camel case.

  • Incidentally, this also permits the name TOptional with a T prefix for a “Throwable” generalization of the class (which arguably does not comply with the GJSG but I find this a useful deviation).

• Removed OverloadMethodsDeclarationOrder, at least because it considers methods that are static the same as non-static ones (see issue 3770).

I renamed the file to distinguish it from the original style.