Coding standards harmony

Posted on

Coding standards

Most mature software development companies or departments define their coding standards.  The intentions is simple; ensure all code looks alike to ease reading, writing, maintaining and communicating code.  As a first effort, these coding conventions may be expressed in some form of standalone document, but conventions that are not being enforced are simply a waste of time.  In the Java world, various tools have existed for some time now, helping us to enforce and adhere to coding standards; Checkstyle, Eclipse and Sonar.   Until fairly recently, it has been laborious to make those tool work together and help us achieve code consistency.  Thankfully, as the mentioned tools matured, it is now possible to define and enforce coding standards effortlessly and the synergy between these tools may even be surprising.

Recap

Lets quickly state the purpose of each tool before we move on.

Checkstyle

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. This makes it ideal for projects that want to enforce a coding standard.

Eclipse formatter

The Eclipse formatter is a set of rules that defines how code will be formatted.

Eclipse clean up

The clean up utility helps to apply formatting rules and coding conventions to a single file or to a set of files in one go.

Eclipse save actions

Save actions are similar to clean up and they define what should happen to the code when a file is saved.  For example, save actions can ensure code is formatted, unused imports are removed and arguments are set to “final” right before the file is saved.

Sonar

Sonar is an open platform to manage code quality.

A common situation

It would be quite common to define coding standards using Checkstyle and including it as part of a project.  Then Eclipse formatter, clean up and save actions would be configured manually to match the Checkstyle rules.  In addition, Checkstyle would run as part of a build to publish the code violations report to a file or to Sonar.  Some better integrated teams would also use the Checkstyle Eclipse plugin in order to see the violations in their code and as code would change and adhere to standards, the Checkstyle Eclipse plugin would reflect that.

Shortcomings

The common situation outlined above is a decent setup but it has some shortcomings.  If the coding standard rules change, that sends a ripple through all the tools.  The Eclipse formatter needs to reflect the new coding standard rules, as well as the clean up and the save actions.  Furthermore, Sonar needs to be updated with the new rules.  In addition, sharing the Checkstyle file between projects and teams can become a choir.  There are ways to define a remote coding standard file used between teams but that does not address the lack of synchronisation between all the tools … until recently.

Harmony

Checkstyle, Sonar and Eclipse have been around for a long time and as these tools matured they developed great integration between them.  By aligning these tools it is possible to establish one central coding standard rule set and reflect those in the development environment automatically.  Furthermore, once configured, changes to coding standards are propagated automatically and developers are always informed about up to date coding standards and apply them as they code.

Example

Lets look at an example on how to best utilise Checkstyle, Eclipse and Sonar.  In addition, to give the example more relevance, lets start with an existing “legacy” project where coding standards have not necessarily been respected.

Assumptions

The example assumes the following:

  • Java project
  • Maven build
  • Checkstyle file expressing the coding standards
  • Sonar
  • Eclipse
  • Eclipse checkstyle plugin
  • Eclipse sonar plugin

Initial coding standard report

We’ll start from the point where an initial Checkstyle configuration has been uploaded to Sonar and a Sonar report has been produced for our existing project.

Reduce violations in IDE

View and reduce violations in the IDE

Next, we’ll configure Eclipse to see those violations closer to the code.  In order to do so, we’ll need to configure the Eclipse Checkstyle plugin with the same rules as Sonar and apply the configuration to the projects.

  1. A link to the Checkstyle configuration
    A link to the Checkstyle configuration
    A link to the Checkstyle configuration 2
    Permalinks
    Checkstyle
  2. Reference to the Checkstyle rules in eclipse (Window > Preferences > Checkstyle > New)
  3. Configure Checkstyle for a project (right click project > Properties > Checkstyle).  Please note the Write formatter/cleanup config checkbox.  This is the part that synchronises the coding standards with the Eclipse formatter and clean up.  You can also right click on your project > Checkstyle > Create Formatter-Profile to achieve the same thing.  This kind of synchronisation alleviates the painful manual synchronisation between Checkstyle and Eclipse; brilliant!
  4. Once Checkstyle has been configured and enabled for a project, notice that violations are annotated by the code
    width="602"
  5. Now that Eclipse has been configured with the coding standard rules and formatting profiles have been updated, we can bulk clean up existing code and go a long way to ensure the code adheres to standards.  After pressing Next > (to review upcoming changes) or Finish, Eclipse would do what it can to help the code to adhere to standards.

    width="602"
  6. After republishing a code standard report to Sonar, we can see a reduction in violations
    width="584"

Save actions

Once the Eclipse formatter and clean up profiles have been updated, don’t forget to update save actions so that as many coding standards are automatically applied as soon as possible (before every save).

Eclipse Sonar integration

Similarly to the Checkstyle Eclipse  plugin, there is a Sonar Eclipse plugin that will annotate code with the violations as seen in Sonar.  In addition to showing Checkstyle violations, the Sonar Eclipse plugin would show Findbugs and PMD violations (all static code analysis tools configured).  The integration is quite simple.

  1. Install the Sonar Eclipse plugin
  2. Identify your Sonar installation
    width="602"
  3. Associate your Eclipse  projects with their Sonar equivalents (notice that your project has to have at least one Sonar report published)
    width="601"
  4. Once the configuration is complete, you can see the violations as published to Sonar annotated in your code
    width="545"
  5. Please note that the code has been annotated with the violations as it was found in Sonar.  If code changes are made, those violations will remain and get out of sync.  Alternatively, you can choose to rerun the checks locally and refresh the violations view.
    width="547"

The usefulness of the Checkstyle Eclipse plugin

Although the Sonar Eclipse plugin may make the Checkstyle Eclipse plugin look superfluous, remember that it is the latter that updates the Eclipse formatting rules as well as the clean up profiles.  If or until the Sonar Eclipse plugin fulfils the same duty, the Checkstyle Eclipse plugin remains very useful.

Not everything can be automated

Please note that although a lot of coding standards can be applied retroactively and automatically, some violations cannot be automatically eradicated.  Nonetheless, Checkstyle, Eclipse and Sonar can identify the problematic code and guide developers towards coding standard compliance.

Conclusion

Coding standards are a preoccupation for most software development teams.  Defining coding standards is one things but enforcing them effectively is another.  Thankfully as Checkstyle, Eclipse and Sonar matured, coding standard definition and enforcement can be a straightforward and a sustainable activity.

One thought on “Coding standards harmony

    Sonar » Sonar in the news said:
    June 7, 2011 at 7:27 pm

    […] Coding Standards Harmony By Marcin Popielarz, 6 May 2011 Most mature software development companies or departments define their coding standards. The intentions is simple; ensure all code looks alike to ease reading, writing, maintaining and communicating code. As a first effort, these coding conventions may be expressed in some form of standalone document, but conventions that are not being enforced are simply a waste of time… […]

Leave a Reply

Your email address will not be published. Required fields are marked *