Java Check-style and Formatting using Maven

Better organised than not.

It is the job of a Software Developer to write a well formatted code following specific code-style. This not just increases the readability of the code, but also makes it easier for someone else to understand and maintain the code in future. However, it can be a cumbersome task to check-style and format already existing code using some pre-defined code-style format especially when the code is in Java language.

It’s easy to make a mess when you’re not the one who has to clean it up.

-Criss Jami

But in today’s world, coders barely have to worry about automating any task in Java. Maven, the build automation tool for Java, already has many plugins to support this task. Here is the breakdown of the entire process into two parts: 1) Enforcing code-style, and 2) Automatic code formatting, to follow a particular style guide.

Enforcing Code Style

Software Used

These steps have been tested with Maven 3.0.4 and Java 1.7

Procedure

Maven has a dedicated Checkstyle plugin, maven-checkstyle-plugin that generates the report of code style violations. It follows a pre-defined style ruleset which can either be a custom file or either of the two predefined files: sun_checks.xml (follows the Sun Code Conventions) or google_checks.xml (follows the Google Java Style Guide). You can include the plugin in the project’s pom.xml file as follows:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-checkstyle-plugin</artifactId>
    <version>2.17</version>
    <executions>
        <execution>
            <id>validate</id>
            <phase>validate</phase>
            <configuration>
                <configLocation>google_checks.xml</configLocation>
                <suppressionsLocation>suppressions.xml
                </suppressionsLocation>
                <encoding>UTF-8</encoding>
                <failsOnError>true</failsOnError>
                <consoleOutput>true</consoleOutput>
                <includeTestSourceDirectory>true
                </includeTestSourceDirectory>
            </configuration>
            <goals>
                <goal>check</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Notice that in the above plugin, <suppressionsLocation> tag is used to define the location of the suppressions.xml file that stores a list of files that should be suppressed from reporting any violations(see suppressions-filter). You can also add the following configurations in the plugin to fail the maven build process on the violation of any style rule defined in the ruleset:

<failOnViolation>true</failOnViolation>
<logViolationsToConsole>true</logViolationsToConsole>

Here, the <failOnViolation> tag is used to fail the build on any violation of the rule. By default, the violation severity is marked as a warning (and not error) for google_checks.xml. To fail the build for warning severity include the following configuration:

<violationSeverity>warning</violationSeverity>

The output logs for violation are visible on the console during the build as follows:

/home/Project/src/test/java/com/check-styling/CheckStyleTest.java:168:54: warning: Should use uppercase 'L'.
/home/Project/src/test/java/com/check-styling/CheckStyleTest.java:7: warning: Import statement for 'org.apache.hadoop.conf.Configuration' is in the wrong order. Should be in the 'THIRD_PARTY_PACKAGE' group, expecting not assigned imports on this line.

Automatic Code Formatting

Software Used

These steps have been tested with Maven 3.3.9 and Java 1.7

Procedure

It is hard to format the entire code base which has been written without following a particular ruleset. For this there are many open-source third-party Maven plugins that use Google Java Style Guide. One of these plugins is the googleformatter-maven-plugin that uses google-java-format dependancy. You can include the plugin in the project’s pom.xml file as follows :

<plugin>
    <groupId>com.theoryinpractise</groupId>
    <artifactId>googleformatter-maven-plugin</artifactId>
    <version>1.7.3</version>
    <executions>
        <execution>
            <id>reformat-sources</id>
            <configuration>
                <includeStale>false</includeStale>
                <style>GOOGLE</style>
                <formatMain>true</formatMain>
                <formatTest>true</formatTest>
                <filterModified>false</filterModified>
                <skip>false</skip>
                <fixImports>false</fixImports>
                <maxLineLength>100</maxLineLength>
            </configuration>
            <goals>
                <goal>format</goal>
            </goals>
            <phase>process-sources</phase>
        </execution>
    </executions>
</plugin>

This plugin does not add or delete anything from the code but only changes the indentation to obey the style guide. You can change the values of various configurations as per your requirements.

I felt the need to use the above two plugins when I started working on a legacy code and was assigned the task to align it with the Google Java Style Guide. Finding the suitable check-styling and code formatting plugins and their versions for the “old code” was a time taking task for me. It made me realise the need to compile all these scattered pieces of the puzzle.

For every minute spent organising, an hour is earned.

-Anonymous

Thank you!