EclipseSource Oomph Profile: Checkstyle

As described in our previous post, we maintain a common Eclipse Oomph Profile with our favorite plugins and settings preconfigured. Using Oomph, you can get this version of Eclipse installed with a single click. See here for a more thorough introduction on how to obtain the pre-configured Eclipse.

As promised, we will describe the things we adapted and added to the standard Eclipse Packages. In the last blog, we started to introduce additional plugins with EclEmma, one of most popular plugins for Eclipse. The next plugin we would like to mention is another evergreen: Eclipse Checkstyle (Eclipse CS), in 2007 it was even awarded Best Open Source Eclipse-based Developer tool. Checkstyle is a tool to ensure your code complies with defined code standards. Checkstyle itself is not specific to Eclipse, there are integrations in almost any tool you can use for Java development, from Netbeans to IntelliJ, from Gradle to Maven. However, we will of course focus on the Eclipse integration, which is part of our Oomph profile.

Static code analysis is probably one the most efficient features of modern code editors and IDEs. It helps developers to avoid bugs at development time. The Eclipse IDE already provides great capabilities to check the code you write, e.g. for uninstantiated variables or unsafe casts. However, when writing code the absence of bugs is only one aspect of the developers task. As code is often used and maintained for many years, it is also very important to write comprehensible code. When working on a framework, this is even more important, as adopters and contributors need to understand its APIs and implementation. Writing comprehensible code is a responsibility of all developers and tooling can only help to improve it. However, when working on a project, it makes things easier to agree on certain rules concerning what comprehensible code means. As an example, you can agree that public methods should be documented or that methods exceeding a certain length should be split into sub-methods. These kinds of rules can then be automatically checked against and provide a guideline for developers how to improve readability.

To activate Checkstyle for a project, right click it in your Eclipse IDE, click “Properties”, select “Checkstyle” in the tree and activate it.

Now, you have to select a Checkstyle Configuration for your project. This configuration specifies the rules which your code is checked against. There are already some pre-configured configurations delivered. You can add new configurations in the general preferences of Checkstyle (Menu “Window” => “Preferences” => “Checkstyle”) and set a default one. Configurations can and should be shared. To do so, you add a new configuration and specify its location. This can be a remote location (e.g. a web server) or a local one relative to the project folder. To be able to work offline, we prefer the second option and share the configuration in a separate project in the git repository. As an example, you can share the configuration in a project which contains other release engineering artifacts, such as the target platform.

To adapt a configuration, click on “Configure” next to it. This will open a dialog where you can select and configure the rules to be applied. A detailed description of the possible customizations can be found on sourceforge.

Once you have activated Checkstyle for a project, additional warnings will be displayed after a rebuild in case your code does not comply with the constraints you have set-up in your configuration. For example, if you have configured the need for documentation on public methods, it would look like this:

Checkstyle also has two views, a table based and a chart based, which provide an overview of all violations in your project. You can open them in the menu “Window” => “Show View” => Category “Checkstyle”. However, Checkstyle warnings are also regular warnings, so you can see them in the default Eclipse “Problems View”, too.

As there is an overwhelming set of possible checks and configurations, we recommend to follow the following guidelines:

1. Start with an existing configuration Before you start to reinvent the wheel, have a look at existing configurations. There are a few build-in configurations, but you can also have a look at the configurations open source projects use. Browse through the settings of existing configurations and review what other people have configured. Some settings are obvious, some other might lead to discussions as there might be different opinions, therefore:
2. Review and communicate the configuration A Checkstyle configuration will influence your code style, as long as you apply it. The later you adapt it, the higher the cost in changing the existing code in order to comply with it. For this reason, configurations are typically maintained for a long time without many adaptations. Therefore, you should carefully review the configuration before you apply it and communicate and discuss it with your team. This involves a time investment. Having a configuration to which nobody in the team agrees will lead to developers ignoring it or finding ways to work around it.
3. Check your existing code Usually, you will have some existing code. If you chose a configuration, apply it to your existing code and have a look at the resulting warnings. If there are many existing warnings, this means your configuration does not reflect the current code style that team members are used to. Now there are two options: Fix the warnings in an explicit task. You should explicitly assign time for this task. The alternative is to reconsider the particular check which produces the warnings. In this case you should turn it off, until you have time to really fix it. Fixing warnings needs time and it will not happen just out of nowhere and in parallel to regular development. If a certain check is already violated 100 times, people will not follow it, not even for new code. That is why we recommend to:
4. Maintain a zero warning policy A typical issue with static code analysis tools such as Checkstyle is that nobody cares about the resulting warnings and their number grows over time. One reason is that if you modify existing code which already includes warnings, there is no good visual notice in case you add new ones. Developers will just get used to the warnings markers on all projects. That is why we recommend a zero warnings policy. If a project has no warnings, developers will notice if new ones are added.

We have to admit, the last recommendation is the most difficult one to follow. This is especially true if you have an existing project and you already have a lot of warnings. However, it can still be followed at least for new bundles/projects. An intermediate solution is to disallow the introduction of new warnings. This should also be done, when following a zero warning policy. As Checkstyle can be included in an automated build, you can check this as part of it. We favor a solution where the build fails in case new warnings have been added, which works perfectly in combination with Gerrit. I will describe this in another blog, soon.

The build integration also allows creating statistics about the number and types of warnings in your project. However, in our experience, those numbers are useless if there are no concrete goals and if nobody is enforcing them.

In the end, Checkstyle is just a tool that helps to write code which complies with a given set of rules, nothing more, nothing less. It is comparable with a spell checker or grammar check review in a text editor. It does not check if the code makes sense or if the quality is high. For those criteria, code reviews, e.g. with Gerrit are much more efficient.

However, even if there are limitations on what the tool can do, it is still a great and valuable addition to the static checks included in Eclipse. Applied in a good way, it definitely helps to standardize the written code and improve the comprehensibility. That is why it truly deserves to be part of EclipseSource Oomph Profile.

If you know any other great tools like this, of course, it is always possible to install it into your IDE and therefore extend our Oomph profile. If you think a certain plugin might be interesting for the majority of users, please get in touch with us, so we can consider adding it to the original profile.

You can report issues and feedback using this github project.

In our next blog posts, we will describe some more of the additional plugins we added to our Oomph profile. For an overview, all posts are linked here. I will also post all updates on the profile in this blog, so please follow us to be notified about those.

Until then, have fun using the EclipseSource Oomph Profile!