How to use Checkstyle in your Java projects

2 minute read

Header

We have seen how to spot bugs in your Java projects by using the SpotBugs plugin or PMD and I couldn’t leave Checkstyle out, since it is one of the most important tools within the Java space, although it is not only focused on detecting bugs or design problems, but also helps development teams to write Java code that adheres to coding standards.

Checkstyle, as PMD and SpotBugs, uses static analysis as well.

Checkstyle can be used as a standalone tool [1], as an Ant Task or by configuring its Maven Plugin [2]. The Maven Plugin uses Checkstyle 8.29 by default, which is not the latest one (8.41) and Java 8. The following is the minimal configuration to add the Checkstyle Maven plugin to the our project:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-checkstyle-plugin</artifactId>
    <version>3.1.2</version>
    <configuration>
        <!-- sun_checks.xml, google_checks.xml or any other-->
        <encoding>UTF-8</encoding>
        <consoleOutput>true</consoleOutput>
        <failsOnError>true</failsOnError>
    </configuration>
    <executions>
        <execution>
            <phase>verify</phase>
            <goals>
                <goal>check</goal>
            </goals>
        </execution>
    </executions>
</plugin>

The plugin is configured to be triggered during the verify phase:

mvn verify

Checkstyle is typically configured by using one of the two most prevalent coding standards, which are Sun Code Conventions (it is the default one) and Google Java Style, but it can be tailored to your needs by using a specific ruleset.

The above configuration uses the minimal configuration with the Sun Code Conventions sun_checks.xml, which is equivalent to add:

<configuration>
    <configLocation>sun_checks.xml</configLocation>
    <encoding>UTF-8</encoding>
    <consoleOutput>true</consoleOutput>
    <failsOnError>true</failsOnError>
</configuration>

If you need to avoid verifying with Checkstyle for some reason, just use:

mvn verify -Dcheckstyle.skip

As mentioned before, the Maven Plugin uses the version 8.29 by default, but it can be configured to use other versions:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-checkstyle-plugin</artifactId>
    <version>3.1.2</version>
    <dependencies>
        <dependency>
            <groupId>com.puppycrawl.tools</groupId>
            <artifactId>checkstyle</artifactId>
            <version>8.41.1</version> <!-- Set your version here -->
        </dependency>
    </dependencies>
    <configuration>
        <!-- sun_checks.xml, google_checks.xml or any other-->
        <encoding>UTF-8</encoding>
        <consoleOutput>true</consoleOutput>
        <failsOnError>true</failsOnError>
    </configuration>
    <executions>
        <execution>
            <phase>verify</phase>
            <goals>
                <goal>check</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Sun Code Conventions are a little aged, so I’d recommend the Google ones [3]:

<configuration>
    <configLocation>google_checks.xml</configLocation>
    <encoding>UTF-8</encoding>
    <consoleOutput>true</consoleOutput>
    <failsOnError>true</failsOnError>
</configuration>

But using a so comprehensive ruleset, as the Google One, can spot an overwhelming number of warning and errors that you might not want to apply, at least from the very beginning, not to mention that some of the rules might be controversial [4], for example, Google’s ruleset enforce 2 spaces for indentation instead of 4 and it is very picky with formatting for JavaDocs, etc. That’s why it is useful to specify your own ruleset, typically based on other’s to not start from scratch; to do so, you can download the latest version of the Google’s ruleset [5] and customize it. The following is an example on how to use 4 spaces to indent instead of 2.

...
<module name="Indentation">
    <property name="basicOffset" value="4"/>
    <property name="braceAdjustment" value="0"/>
    <property name="caseIndent" value="4"/>
    <property name="throwsIndent" value="4"/>
    <property name="lineWrappingIndentation" value="4"/>
    <property name="arrayInitIndent" value="4"/>
</module>
...

Be careful with the version of the ruleset you download, since it must be compatible with the specified version of checkstyle. Many people just download the desired version from the release page and extract the ruleset from it.

The following is the final configuration for maven using a specific ruleset my-checkstyle.xml ready to be used within your projects.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-checkstyle-plugin</artifactId>
    <version>3.1.2</version>
    <dependencies>
        <dependency>
            <groupId>com.puppycrawl.tools</groupId>
            <artifactId>checkstyle</artifactId>
            <version>8.41.1</version> <!-- Set your version here -->
            </dependency>
    </dependencies>
    <configuration>
        <configLocation>my-checkstyle.xml</configLocation>
        <encoding>UTF-8</encoding>
        <consoleOutput>true</consoleOutput>
        <failsOnError>true</failsOnError>
    </configuration>
    <executions>
        <execution>
            <phase>verify</phase>
            <goals>
                <goal>check</goal>
            </goals>
        </execution>
    </executions>
</plugin>

There are other important topics, as exceptions, multi-module configuration or how to configure Checkstyle within your favorite IDE, but let’s keep this post short enough and I’ll cover those in others.

You may also enjoy