Maven: A Developer's Notebook

Reporting on Code Best Practices

When you're working in a team it's good to define development best practices to be used by all the developers. That's great, but how do you enforce their usage? Code reviews? Nah, that's the old way of doing it! Nowadays there are powerful tools to help verify that best practices are applied throughout the code. Some of these tools include Checkstyle (http://checkstyle.sourceforge.net/), PMD (http://pmd.sourceforge.net/), and Findbugs (http://findbugs.sourceforge.net/).^[2] Let's discover how to use the Checkstyle plug-in.

How do I do that?

Add a Checkstyle report to the qotd/core project's POM:

  <reports>
    <report>maven-checkstyle-plugin</report>
    [...]

If you run maven site now you'll get a Checkstyle report, as shown in Figure 4-6. Notice that the cells in Line column can be clicked. They are links to the JXR report described earlier, showing the code lines causing the violation.

Figure 4-6. Typical Checkstyle report

You may wonder where the rules to apply have been defined. By default the Checkstyle plug-in uses a default configuration file. However, it's very unlikely it'll match your project's coding conventions. You'll need to customize it by adding a property in qotd/core/project.properties, pointing to a Checkstyle XML configuration file:

maven.checkstyle.properties = ${basedir}/../common/checkstyle.xml

Tip

Don't forget that you must use ${basedir} if you want it to work when building the site using the Multiproject plug-in. This is because the Multiproject plug-in is executed from the top-level directory in qotd/, and without ${basedir} it'll look for the checkstyle.xml file in the wrong place.

It's a good idea to put the checkstyle.xml configuration file in common/, as you'll share this file with all the QOTD subprojects. Here's a snippet of a typical checkstyle.xml file:

<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
    "-//Puppy Crawl//DTD Check Configuration 1.1//EN"
    "http://www.puppycrawl.com/dtds/configuration_1_1.dtd">
  
<module name="Checker">
  <module name="TreeWalker">
    <module name="AbstractClassName"/>
    <module name="AvoidStarImport"/>
    <module name="ReturnCount"/>
    <module name="GenericIllegalRegexp">
      <property name="format" value="System\.(out|err)\."/>
      <property name="message" 
          value="Don't write directly to System.out our System.err"/>
    </module>
[...]

The full descriptions of all checks are available on the Checkstyle web site (http://checkstyle.sourceforge.net). The four checks listed earlier perform the following checks:

• Verify that abstract class names start with the Abstract keyword

• Verify that imports are qualified and do not use the some.package.* shorthand notation

• Verify that methods returning a value have a single return point

• Verify that System.out and System.err are not used

Checkstyle provides hundreds of checks, and it's also possible to write your own extensions.

This is nice, but is it useful? The short answer is no! Reporting on best practices that are not applied does not make the code better. The best solution is to sort the different checks and categorize them by severity with your team. As you can see in Figure 4-6 in the Files table, Checkstyle supports three types of severity checks: errors (E column), warnings (W column), and infos (I column). For example, to have the AvoidStarImport rule as a warning, define it as follows in checkstyle.xml:

    <module name="AvoidStarImport">
      <property name="severity" value="warning"/>
    </module>

Then make the build fail for the error category. You do this by setting the maven.checkstyle.fail.on.violation property to true:

maven.checkstyle.fail.on.violation = true

What about...

...using PMD?

PMD and Checkstyle are very similar. Each tool has rules that the other does not have, so using both of them makes sense. Using PMD with Maven is very simple: add the maven-pmd-plugin report to the reports section of the POM.

And what about using Findbugs?

It's a nifty tool in the same category as Checkstyle and PMD. However, it's even more focused toward finding semantic errors than syntactic ones. You are really encouraged to use it in addition to Checkstyle and Maven. You'll be surprised by its findings! To use it with Maven, add maven-findbugs-plugin to your reports. However, you must install the Findbugs plug-in first—it's not part of the Maven distribution. You can find it at http://maven-plugins.sourceforge.net/repository/maven-plugins/plugins/. Refer to Appendix A or Chapter 6 to learn how to install a Maven plug-in.

You may also want to investigate JDepend (http://www.clarkware.com/software/JDepend.html) and JavaNCSS (http://www.kclee.de/clemens/java/javancss/). These tools also have Maven plug-ins to help you assert the quality of your code.

---

^[2] There's a list of other verification tools at http://pmd.sourceforge.net/similar-projects.html.