Style: It's a Mad Man Who Pretends He Doesn't Want It... (a.k.a. Checkstyle)

Overview

Any seasoned developer wears the scars of a braces war... if the decision as to which is preferred:

if ( ... ) {
    // do this
} else {
    // do that
}

if ( ... ) 
{
    // do this
}
else 
{
    // do that
}

if ( ... ) 
  {
    // do this
  }
else 
  {
    // do that
  }

if ( ... ) 
    {
    // do this
    }
else 
    {
    // do that
    }

... fills you with dread and triggers flashbacks^[1] ... we know your pain... every developer has their view on what is the one true brace style and, being a disagreeable bunch at the best of times, everyone else's style is moronic at best (Note: I am not saying any of the above styles are/are not the one true brace style).

But move past the flashbacks... when you are maintaining an existing codebase, it is a joy to find that the code base is consistently styled... we can disagree on what the styling should look like, but once a victor has been established for a code base, maintaining the code can be easier.

For Java code, there is a well known utility for checking compliance with a coding style... Checkstyle . You describe your team's victorious code style (the one that everyone hates because management forced a decision and gave everyone at least one win) and you can now measure the project's compliance with the coding style.

At a previous employer, we had the braces war. We set up the Checkstyle ruleset, and then we promptly did what everyone else does...we forgot all about it. Developers never ran Checkstyle on their changes, and the code just kept on getting messier and messier...

Shortly afterwards, I set up a Jenkins (well, it had a different name at the time) server, and a co-worker (Peter Reilly) knocked together a very rough and ready Checkstyle plugin^[2] ... strangely just by adding a graph of the number of Checkstyle violations, without any other prodding, the number of Checkstyle violations went from 60,000+ to less than 20 in the space of about six months! The code base was a lot tidier and easy to maintain. Victory... all because Mr. Jenkins was reporting the Checkstyle metric for the developers... they didn't have to remember to run Checkstyle... and when they were stuck on a hard problem, they could always tidy up some code (a mind-numbing task) while their subconscious solved the hard task.

In any case, the Jenkins Checkstyle plugin is one plugin that you can use to try to replicate that feat for yourself on your projects... assuming you survive the process of picking which one, true brace style to use, that is!

Stable Release Version

The latest release is 3.24 which was released in March 2012.

Requirements for Plugin Use

This plugin requires Jenkins 1.409 or newer, as well as the Analysis-Core  plugin version 1.38.

Step-by-Step Instructions on How to Use the Checkstyle Plugin

Installation

1. Go to your Jenkins instances root page.
2. If your Jenkins instance has security enabled, login as a user who has the Overall | Administer permission.
3. Select the Manage Jenkins link on the left-hand side of the screen.
4. Select the Manage Plugins link.
5. On the Available tab, select the Checkstyle Plugin and click the Download and Install button at the bottom of the page. (All the required dependent plugins will automatically be downloaded for you.)
6. (If you are using a version of Jenkins prior to 1.442) Restart Jenkins once the plugins are downloaded.

Configuration

Before you can use this plugin you must ensure that your job is generating Checkstyle reports. The Jenkins plugin will not run Checkstyle for you . It will report the results that your build produces.

With Maven-based projects, this is usually a case of ensuring that the maven-checkstyle-plugin is executed during your build. With ANT-based projects, you will need to ensure that your build invokes the Checkstyle ANT tasks, while other build systems will have their own integrations.

Usually the Checkstyle results will be saved in an XML file called checkstyle-results.xml. If you are that lucky, then enabling the plugin is just a matter of selecting the Publish Checkstyle analysis results checkbox in the Post-build Actions:

With the Freestyle project type there is a text box where you can enter the filename pattern that the plugin will use to find the checkstyle XML results. The text box assumes that the pattern is **/checkstyle-results.xml unless you enter an alternative pattern, so 99 times out of 100 you can just leave the text box empty.

If you are using the Maven project type, the plugin will capture the XML filename(s) from the Maven plugin, so there is no need to configure the filename pattern, and as a result there is no text box to fill in!

Tips & Tricks

There are some additional advanced options available if you click on the Advanced button for the Checkstyle analysis plugin:

• By default, the plugin only runs for stable or unstable builds (on the assumption that you only run the Checkstyle reports when the code compiles). If you need the reports to be collected for every build, just enable the Run always option.

• If you are using a Freestyle project^[3] with an ANT or Maven multi-module project, you may want to see the reports broken down by module. You can ask the plugin to try and auto-detect the modular structure of your build by enabling the Detect modules  option.

• Set 0% health to the current number of Checkstyle errors, e.g. 10,000. Set 100% health to somewhere between 20 and 50% better than your target, e.g. 9,300. Set the status thresholds so that unstable is about 10% of your target, e.g. 9,950 and failed is slightly worse than where you are, e.g 10,001:

The result will be that developers will be prodded into fixing some Checkstyle issues (as the build will be called out as unstable) and prevented from letting things get worse (as the build will be marked as failed if that happens) and once some progress has been made, the weather reports will start to improve, giving a nice subtle nudge... just the kind of positive feedback that works.

How to Use it on DEV@cloud

If you are using the CloudBees Platform as a Service (PaaS), the plugin is identical to configure on DEV@cloud.

Any Known Issues

• The Checkstyle plugin can be somewhat demanding on memory, if your project has a very large number of Checkstyle violations, you may have to resort to either fixing a large chunk of them or switching to the Violations plugin which is uses a different parsing engine and usually maintains a lower memory footprint.
• Some people using the Jenkins Maven Project type have reported that for some structures of their pom.xml files, the plugin does not notice when the maven-checkstyle-plugin is run on a build which only invokes the main lifecycle.

Relevant Documentation

• The Jenkins Plugin Wiki Page

- Stephen Connolly
Elite Developer and Architect
CloudBees
cloudbees.com

^{[1] Possibly to a time from before you assumed somebody else's identity .  
[2] Peter's plugin went on to evolve into the Violations Plugin  which also can be used to report Checkstyle results. To understand why there are two plugins risks opening a can of worms... Peter does not use Maven for building his own projects... favoring ANT for some reason or other ... Peter usually asked me for help if he had issues with Maven... I am not sure why ;-). Add into the mix my disapproval of the Jenkins Maven Project Type ... and you might have some guesses as to why the Violations plugin did not, for a long time, support the Jenkins Maven Project Type (Note: freestyle projects with a Maven build step were always supported... and the Maven Project Type has been supported since May 2008 anyway)
[3] And I always do.}