Improve code readability by using coding rules

The programming style, coding standards or coding rules, all refers to a set of guidelines, best pratices, conventions that developers use when writing source code. All developpers have their own habits, nevertheless, if all developpers conform to the same standard, the consistency through the project will ease maintenability, code review and so on. One of the goal is to improve code quality, but also the daily life of the developper by defined common rules to ease communication.

Defining a set of rules is an arbitrary process, the most important things is to have a consensus through the teammates on the selected rules.

CheckStyle gradle plugin task

To integrate CheckStyle into your Gradle build script, add the following snippet into your build.gradle as described on the Gradle plugin website :

1
2
3

plugins {
    id 'checkstyle'
}

Then you can run CheckStyle with the command line:

1

./gradlew check

Configure which report, xml or html will be generated by using the following snippet:

1
2
3
4
5
6

tasks.withType(Checkstyle) {
    reports {
        xml.enabled false
        html.enabled true
    }
}

The check task generates report as below:

CheckStyle Intellij plugin

One of the simple way to check that you conform to the defined coding rules, is to integrate these checks into your IDE to have feedbacks directly as you write code.

Install the plugin into IntelliJ by going to File/Settings then select Plugins and Browse Repositories. Search CheckStyle-IDEA and install the plugin.

The plugin comes with two predefined coding rules Sun Checks and Google Checks, select the one that you want to use by going to File/Settings, then select CheckStyle and tick the coding rules that you want to use.

The best is to configure the IDE with the same configuration that is used by CheckStyle, such as the IDE will format the code by respecting the coding rules. For instance into IntelliJ you can set the coding scheme to use by going to File/Settings, then Editor/Code Style/Java, then select Import Scheme/CheckStyle Configuration.

CheckStyle can be run by clicking the run button into the CheckStyle view (show it by going to View/Tool Windows/CheckStyle) or by executing an action Ctrl-Shit-A, then Check Current File action.

CheckStyle configuration

As already saw, CheckStyle is shipped with at least two predefined configurations: Sun Checks and Google Checks. At some point, you probably needs a custom configuration which fullfills your own set of coding rules defined by your teams. You can easily defined it by adapting a predefined configuration.

It can be done in two ways, the first is to use the Eclipse IDE with the eclipse-cs plugin, which allows to edit configuration.

Install the eclipse-cs plugin by going to Help/Install New Software..., then set Work with with the URL of the plugin version 8.12 https://dl.bintray.com/eclipse-cs/eclipse-cs/8.12.0/, then tick CheckStyle and click Finish.

Once the plugin is installed, go to Window/Preferences, select CheckStyle, copy one of the existing configurations that you want to custom, then configure it. Thereafter, you can export your custom configuration as an XML file.

❗ IntelliJ does not allow to edit CheckStyle configuration.

The other way to define a custom configuration is to directly update the XML file of an existing configuration. The Google Checks configuration can be download from GitHub. Refer to the official configuration documentation to understand how the XML file is structured.

For instance, in order to enable the module AvoidNestedBlocks, add the following snippet into the XML configuration file under the item <module name="TreeWalker">.

1
2
3

 <module name="AvoidNestedBlocks">
    <property name="allowInSwitchCase" value="true"/>
 </module>

By default, the language used to generate error messages come from the default locale country and language of the Java Virtual Machine. If it is not suitable, you can select the language used to report errors by adding the following snippet into the XML configuration.

1
2

<property name="localeCountry" value="EN"/>
<property name="localeLanguage" value="en"/>

Publish CheckStyle report into Jenkins

CheckStyle can be easily integrated into Jenkins, one of the leading open-source automation servers. Use it through docker with the following command line:

1

docker run --name jenkins -d -v jenkins_home:/var/jenkins_home -p 8080:8080 -p 50000:50000 jenkins/jenkins:lts

Now install the Warnings plugin by going to Manage Jenkins/Manage Plugins, into available plugins select Warnings Next Generation and install it without restart.

In order to add CheckStyle analysis into your build job, go to the project and select Configure, into the Build section, add a build step that will invoke gradle script and set the tasks to check. To finish, into the Post-build Actions, add a step to Record compiler warnings and static analysis results to publish CheckSyle results and set the Report File Pattern to **/build/reports/checkstyle/main.xml which represents the path where the CheckStyle report is generated.

❗ Do not forget to configure the tool to generate the XML report as describe previously.