Coding conventions are a set of guidelines for a specific programming language that recommends programming style, practices, and methods for each aspect of a program written in that language. Reducing the cost of software maintenance is the most often cited reason for following coding conventions. Code conventions are important to programmers for a number of reasons, in their introduction to code conventions for the Java programming language, Sun Microsystems provides the following rationale⁵:
- 80% of the lifetime cost of a piece of software goes to maintenance.
- Hardly any software is maintained for its whole life by the original author.
- Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
- If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
Most of the software today is written by using a version control system like Git and mechanisms for peer-review alike pull requests. By introducing an automated coding convention you eliminate the time spent by reviewers on subjective styling opinions or styling errors.
Integration
As an example in this tutorial, we’ll integrate the Google Java Style Guide withing the Algo open source project. Along with the official convention definition, Google developed thegoogle-java-format
program that reformats the Java source code to comply with the coding style. We’ll be using a third-party Gradle plugin (i.e. google-java-format-gradle-plugin
) to automate and integrate the coding style. Below follow the steps:
- Add the following to your
build.gradle
file:
plugins {
id 'com.github.sherter.google-java-format' version '0.8'
}
That’s it, all done! Easy!
The added Gradle plugin adds the tasks goJF
and verGJF
, i.e. more specifically:
a) Execute the following task to format all *.java
files in the project according to the coding style (see Animation 1):
./gradlew goJF
b) Execute the following task to verify that all *.java
files are formatted properly:
./gradlew verGJF
Configuring the Google Java Format Gradle Plugin
By default, the plugin fails the build in case a file is not following the convention. If you just prefer to display a warning then add the below instruction to your build.gradle
file:
tasks.verifyGoogleJavaFormat.ignoreFailures = true
There is also a handy third-party pre-commit hook which will run Google’s Java code style formatter for you on your code, see google-style-precommit-hook
.
You can adjust the variable toolVersion
to use a specific version of google-java-format
, e.g. add the below instruction to your build.gradle
file:
googleJavaFormat {
toolVersion = '1.1'
}
Choose between 'GOOGLE'
(default) and'AOSP'
style by setting the style option:
googleJavaFormat {
options style: 'AOSP'
}
IntelliJ Integration
A google-java-format IntelliJ plugin is also available from the plugin repository. To install it, go to your IDE’s settings and select the Plugins
category. Click the Marketplace
tab, search for the google-java-format
plugin, and click theInstall
button. The plugin will be disabled by default, you need to enable it manually.
Alternatively, you can import the coding style in the IDE. Download the IntelliJ Java Google Style file, then go to IntelliJ IDEA
→Preferences
→Editor
→Code Style
→Java
→Config Button
(near theScheme
label)→Import Scheme
→IntelliJ IDEA code style XML
→now select the previously downloaded file.
There are also plugins for Visual Studio Code, Eclipse, Android Studio, and other JetBrains IDEs, just do a quick query on a search engine.
Conclusion
Within this article, we have briefly illustrated how to easily and quickly integrate the Google Java Style Guide in a Java project. Even though this convention is widely spread it’s not the only candidate, you may also consider the Sun Code Conventions and Checkstyle, even though it’s antiquated, verbose and quite difficult to integrate.
As perfection is just an illusion, so are the tools, below are the Cons and Pros of the approach illustrated in this article:
Cons:
- No flexibility, it is completely inflexible by design², you will not be able to change any formating of the coding style.
- 2 space indentation instead of 4 spaces, this irritates the nose of lots of software engineers, you will not be able to enforce such a preference (see the previous bullet point), you may consider the
'AOSP'
(i.e. Android Open Source Project) style which has 4 spaces for indentation
Pros:
- Good community support.
- Automated, it’s there, it works, and you don’t even think about it.
- Easy integration in IntelliJ, Eclipse ….
- Lots of available tools, plugins.
- Easy to adopt, integrate and maintain (1 minute of effort).
Last modified date: 28/07/2019