The Ultimate Guide to Checkstyle: Unleashing the Power of Code Quality
CheckStyle is a development tool to help programmers write Java code that adheres to a coding standard. It automates the process of checking Java code to spare humans of this boring (but important) task.
With this , we can make some static code checks such as file formatting, limiting imports, annotations, block checks, class design etc. This makes it ideal for projects that want to enforce a coding standard in large projects where a large number of people work on a single project. As they can’t check manually what each and every developer is doing, tools like CheckStyle can come in very handy just in case there might be a mistake done by a developer which might go unnoticed. Let us see how do we integrate this tool in our project.
Configure CheckStyle in IDE
For development, CheckStyle has many plugins available in various IDE, below is an example using IntelliJ IDEA.
In IntelliJ, you can go to (“File > Settings > Plugins”) and search for CheckStyle plugin in the IDEA marketplace.
After the installation , we can configure CheckStyle with various option. By default, CheckStyle supports Sun and Google coding conventions. We can also configure it to use our own configuration by mentioning our configuration file.
Now, we can check our project with the configured ruleset anytime by going to the CheckStyle tab and running the check on the whole project or any file of your choice.
CheckStyle plugins are present for other popular IDEs as well such as VSCode and Eclipse.
Configure CheckStyle in build
What if we wanted to configure the ruleset to check the project files while we build the project? This will improve our code quality checks when our project is going live. This will also prevent our code from having bugs which could have been easily removed if we had adhered to the standard.
Luckily, CheckStyle offers us the flexibility to configure itself to the build lifecycle. Below is an example on how to do it in Maven. Firstly, in the maven pom file of the project, we would have to necessarily specify the following:
- In which maven lifecycle event we would trigger the check (compile, verify, install etc.)
- Any custom configuration file used for running the checks.
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<version>3.2.1</version>
<configuration>
<configLocation>checkstyle.xml</configLocation>
</configuration>
<executions>
<execution>
<id>validate</id>
<phase>validate</phase>
<configuration>
<encoding>UTF-8</encoding>
<consoleOutput>true</consoleOutput>
<failsOnError>true</failsOnError>
<failOnViolation>true</failOnViolation>
<suppressionsLocation>checkstyle-suppressions.xml</suppressionsLocation>
</configuration>
<goals>
<goal>check</goal>
</goals>
</execution>
</executions>
</plugin>In the above code snippet, we have configured CheckStyle to check on the validate phase of the maven build lifecycle. We have also defined the custom file with the set of rules named checkstyle.xml with the <configLocation> tag. There are also some other configurations set up such as the build would fail if the CheckStyle check gives an error(denoted by the <failsOnError> and <failsOnViolation> tags) and to give the checkStyle output to console (denoted by the <consoleOutput> tag).
Here is a nice article to configure CheckStyle using Gradle, another popular build tool.
Write your own CheckStyle configuration file
CheckStyle defines each rule to be checked as a set of tags, each tag defining one rule where we can configure some parameters for each rule inside the rule tag. List of tags are given in this link.
To write our custom rules, we would have to define an XML file(preferably in the root folder). I am naming it checkstyle.xml. This is the filename which goes inside the <configLocation> tag inside configuration(See snippet above). Below is an example of a sample CheckStyle ruleset file.
<?xml version="1.0"?>
<module name="Checker">
<!--Checks for whitespace -->
<!--See http://checkstyle.org/config_whitespace.html -->
<modulename="FileTabCharacter">
<propertyname="eachLine"value="true"/>
</module>
<modulename="LineLength">
<propertyname="fileExtensions"value="java"/>
<propertyname="max"value="100"/>
</module>
</module>As we can see from the above snippet, we can list the checks we would want to perform as tags in the xml file. Each check must be defined inside the module named Checker(See Line 6). In the above example , I have put up two checks, one for checking any unnecessary whitespaces and the other for checking the number of lines in a file. We can also configure some properties related to the rules like the maximum number of line allowed(set as 100 above using the max property).
Suppress Rules for specific files
We can also define a suppression file to suppress some rules on selected files. This is the filename which goes inside the <suppressLocation> tag inside configuration(See Snippet above). Below is an example of CheckStyle suppress XML file.
<?xmlversion="1.0"?>
<suppressions>
<suppresschecks="FileLength"
files="FooBar.java"/>
</suppressions>Here I have suppressed the rule of FileLength on a single file “FooBar.java”. Each suppression must be defined inside the <suppressions> tag as shown above.
Limitations of CheckStyle
There are some limitations of CheckStyle as a code quality checker.
- As it is static code quality checker, it won’t be able to know about possible logical errors which might bring some bugs into the code.
- It is available only for Java.
- In CheckStyle , each file is checked only one by one , so we wouldn’t be able to do some checks which requires checking multiple files at once such as finding any unused public function etc.
In all , if you are working on a Java project, using CheckStyle for static code analysis is a good choice as it is open source, lightweight and highly configurable. There are some language agnostic static code analysers as well such as SonarQube, PMD and many more which offer a more comprehensive set of code checks for your projects.
