Checkstyle is a tool that can be used by developers in order to help teams follow coding conventions on a Java project. I recently used this whilst developing a Battleships game in Java with a group of others as part of a university module (maybe a post for another day?..).

Why use Checkstyle?

Coding conventions and standards are a way to ensure that code is formatted consistently across a project, team or organisation. The benefits of using them are pretty well known and well documented but it essentially comes down to making the code more readable and accessible to yourself and other developers.

Checkstyle helps developers to follow a coding convention by pointing out errors or warnings within the IDE based on an XML configuration file that you provide in the project. The configuration file’s format is well documented, easy to read and easy to edit. On our project we chose to base our standards on Google’s guidelines (google_checks.xml) which we then adapted to suit our own coding style (checkstyle.xml). We also used Travis CI to build our project each time someone pushed new code and if compilation and tests passed then we would get a notification in our team’s Slack channel, similarly if anything went wrong we would get a notification to let us know we needed to fix something. As we were using Checkstyle with the Maven plugin this meant that if code was committed which didn’t comply with our standards then the build would fail¹.

How to install & use Checkstyle

Installing and getting Checkstyle to work with Maven initially took a few attempts and gave quite the headache but I put that down to my lack of experience with Maven and in the end it was worth it. I’m hoping that by documenting the process here others will be able to save time by not having to follow my process of trial and error!

Maven

In the pom.xml put the following block of code into the section.

<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>
				<encoding>UTF-8</encoding>
				<configLocation>checkstyle.xml</configLocation>
				<consoleOutput>true</consoleOutput>
				<failsOnError>true</failsOnError>
				<linkXRef>false</linkXRef>
			</configuration>
			<goals>
				<goal>check</goal>
			</goals>
		</execution>
	</executions>
	<dependencies>
		<dependency>
			<groupId>com.puppycrawl.tools</groupId>
			<artifactId>checkstyle</artifactId>
			<version>7.6</version>
		</dependency>
	</dependencies>
</plugin>

Note – the configLocation field can be removed and Checkstyle will use the default config (sun_checks.xml) but as mentioned earlier on our project we used a custom configuration and simply named it “checkstyle.xml” in the root of our project.

It’s also worth mentioning the dependencies section where we explicitly tell Maven to use version 7.6. Without this section Maven will use version 6.11.2. This was something I only solved recently but it prevented us from using some of the newer checks available during development.

After setting up the configuration file (or choosing to use the default) running ‘mvn validate’ in the command line should give you the following output.

...
[INFO] --- maven-checkstyle-plugin:2.17:check (validate) @ Battleships ---
...

Below that line you will see a list of errors or warnings if your code does not follow the defined convention.

That’s it, your project is now set up to run Checkstyle with Maven!

Eclipse

There is also an Eclipse Checkstyle Plugin available for Checkstyle which will allow Eclipse to display errors and warnings to the user in the ‘problems’ tab. This makes it easy for developers to see jump to the offending pieces of code and fix it to comply with the coding standards in the configuration file.

Happy Coding!

¹ The severity of “non-compliance” could be configured to either throw a warning or an error based on which rule had been broken. For example a line length of greater than 100 may throw an error but an extra whitespace somewhere may just cause a warning.