Code Quality Unravelled: Part 1 Building a Maven Site

This is the first installment in a series of posts about code quality, the tools that are available to track quality, and how to configure various systems to get all of the quality reporting.  There are a lot of posts on the internet about all of the tools and configurations that I'm going to describe, however, I thought it would be useful to have it all in one place.

---

Code Quality Unravelled: Part 2

---

Building a Maven Site

Apache Maven is a build tool for Java. There are a ton of plugins to have your build do all sorts of processing and reporting. One of the key components of Maven is the site report. The site report collects all sorts of information about your project including descriptive information, contact information, license information and also various reports.

The pom.xml file is the place where you can configure all of the build information, dependencies, and reporting tools. The Apache Maven site has a great reference to all of the various components that make up a pom file. For the purposes of this post, I am going to focus on the reporting section of the pom file.

NOTE: This post was written using Maven version 3.2.3.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.mycompany</groupId>
    <artifactId>test-java-build</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>test-java-build</name>

    <properties>
      <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <reporting>
      <plugins>
        <!-- This is where we will focus -->
      </plugins>
    </reporting>
</project>

There are a lot of reports that can be generated on the code base using Maven. I'm going to go over how to setup and configure the following tools: Cobertura, PMD/CPD, JXR, Javadoc, Surefire, FindBugs, JDepend, Taglist, Checkstyle.

Cobertura

Cobertura is a tool to report on the amount of code being covered by automated tests.

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>cobertura-maven-plugin</artifactId>
    <version>2.7</version>
    <reportSets>
      <reportSet>
        <id>cobertura</id>
        <reports>
          <report>cobertura</report>
        </reports>
        <configuration>
          <formats>
            <format>html</format>
            <format>xml</format>
          </formats>
        </configuration>
      </reportSet>
    </reportSets>
</plugin>

This block will cause cobertura to generate the report in both xml and html format. You can find other configuration options on the plugin site. NOTE: If you are using Java 8 (specifically the new syntax) and start seeing stack traces referencing JavaNCSS, make sure you upgrade to version 2.7 of this plugin. This version brings in Cobertura 2.1.x which supports Java 8 correctly.

PMD/CPD

PMD analyzes your source code finding common programming flaws. CPD (Copy-paste-detector) also comes with PMD and looks for duplicate code in your project.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-pmd-plugin</artifactId>
    <version>3.5</version>
    <reportSets>
      <reportSet>
        <id>pmd-report</id>
        <reports>
          <report>pmd</report>
        </reports>
        <configuration>
          <skipEmptyReport>false</skipEmptyReport>
        </configuration>
      </reportSet>

      <reportSet>
        <id>cpd-report</id>
        <reports>
          <report>cpd</report>
        </reports>
        <configuration>
          <skipEmptyReport>false</skipEmptyReport>
        </configuration>
      </reportSet>
    </reportSets>
</plugin>

This block will run both PMD and CPD and include the reports regardless of whether there are issues detected or not. Plugin configuration options can be found on the plugin site. One key section to take a look at in the documentation is the Rule Set section. This shows you how to define or customize the rules you want PMD to check against.

JXR

JXR is plugin that produces an html view of all of the source in the project. This plugin is also used by other reports in order to link directly to the source.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jxr-plugin</artifactId>
    <version>2.5</version>
</plugin>

Javadoc

The Javadoc plugin will generate the Javadoc for your project and include the documentation in the site output.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.10.3</version>
</plugin>

Note: if using JDK 8 or newer, the Javadoc command has added a strict validator that checks for broken references and invalid HTML. This validator will fail the build if it finds anything it deems unacceptable. There is a good run down on this behavior on this blog. To have maven still present the warnings but not fail the build a configuration section can be added to the plugin definition like so:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.10.3</version>
    <configuration>
      <additionalparam>-Xdoclint:none</additionalparam>
    </configuration>
</plugin>

JavaNCSS

The JavaNCSS Plugin generates metrics for quality and complexity on the project.

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>javancss-maven-plugin</artifactId>
  <version>2.1</version>
</plugin>

Surefire

The Surefire Report Plugin generates a nice easy to read report of all of your test results.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-report-plugin</artifactId>
    <version>2.18.1</version>
    <reportSets>
      <reportSet>
        <id>unit-tests</id>
        <reports>
          <report>report-only</report>
        </reports>
        <configuration>
          <linkXRef>true</linkXRef>
          <alwaysGenerateSurefireReport>true</alwaysGenerateSurefireReport>
        </configuration>
      </reportSet>
    </reportSets>
</plugin>

This block will generate the surefire report without running the tests a second time (the default report "report" type runs the tests twice). The configuration option linkXRef links the line references in the tests to the actual source provided by JXR. The alwaysGenerateSurefireReport option will generate the surefire report whether all of the tests pass or not.

FindBugs

FindBugs analyzes the code looking for potential bugs.

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>findbugs-maven-plugin</artifactId>
    <version>3.0.2</version>
</plugin>

JDepend

JDepend looks through the source tree analyzing the quality of the code in terms of extensibility and reusability.

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>jdepend-maven-plugin</artifactId>
    <version>2.0</version>
</plugin>

Taglist

The Taglist plugin searches the code for various defined tags that are used to highlight areas of code that need more attention (e.g. TODO and FIXME).

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>taglist-maven-plugin</artifactId>
    <version>2.4</version>
    <reportSets>
      <reportSet>
        <id>taglist-report</id>
        <reports>
          <report>taglist</report>
        </reports>
        <configuration>
          <tagListOptions>
            <tagClasses>
              <tagClass>
                <displayName>Todo Work</displayName>
                <tags>
                  <tag>
                    <matchString>todo</matchString>
                    <matchType>ignoreCase</matchType>
                  </tag>
                  <tag>
                    <matchString>FIXME</matchString>
                    <matchType>exact</matchType>
                  </tag>
                </tags>
              </tagClass>
              <tagClass>
                <displayName>Architecture Review Needed</displayName>
                <tags>
                  <tag>
                    <matchString>ARCH-REV</matchString>
                    <matchType>exact</matchType>
                  </tag>
                </tags>
              </tagClass>
            </tagClasses>
          </tagListOptions>
        </configuration>
      </reportSet>
    </reportSets>
</plugin>

This block configures taglist to search for the TODO tag (regardless of case), FIXME tag, and a custom ARCH-REV tag.

Checkstyle

Checkstyle is similar to PMD and FindBugs but instead of search for potential bugs focuses more on keeping a consistent coding style across the project.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-checkstyle-plugin</artifactId>
    <version>2.16</version>
</plugin>

The Checkstyle maven plugin has a lot of options to help configure the level of warnings and errors to include in the generated report. The plugin documentation has some good examples of adding extra configuration to customize the items that Checkstyle will check for you.

Generating the site

Now that we have all of our reports configured we can easily generate our maven site by running the following:

mvn clean test site

When the command is finished running you should have a directory under the target folder. This site folder contains all of the files needed to display the html website.

For a sample project that includes all of these reporting sections check out the repo on Github.

---

Code Quality Unravelled: Part 2

---