Ben Northrop


Decisions and software development


PMDReports


March 2nd 2008


PMDReports is a wrapper around the popular open-source Java code analysis and bug detection tool, PMD. Whereas PMD generates and displays code quality statistics at a source code level, PMDReports persists and aggregates these statistics so that code quality can be viewed from a more macro, component level. From this elevated perspective, development team members can begin to better understand:

  1. Which components in a project have the best or worst code quality?
  2. As development continues, is code quality improving? Or getting worse?
  3. How does code quality in this project compare to other projects?

Below are a couple of screen shots from PMDReports.

Code Quality Trend Graph Detail Report

I wrote a quick getting started guide in my blog, but below is more detailed documentation. Please note that PMDReports can be downloaded, configured, and run within about 5 minutes - so don't be turned-away by the text in this document. It's extremely easy to get up and running quickly.

Table of Contents
  1. Download
  2. Configure
  3. Run

Lastly, if you have any questions or problems with PMDReports, feel free to shoot me an email at ben_northrop at yahoo dot com.

Download

PMDReports for the Windows platform is currently in a Beta stage. Version 0.7.4 can be downloaded here. The only prerequisites are:

Once downloaded, unzip to any directory (e.g. C:\Program Files\PMDReports).

Configure

The PMDREPORTS_HOME/projects.xml file must be configured to tell PMDReports which projects and components to analyze. Below is a simple example:

<?xml version= "1.0" encoding= "UTF-8"?>
<projects>
   <project name="AbcProj" srcroot="C:\projects\abcproj" >
     <component name="Manager" src="\manager\src " />
     <component name="Web Services" src="\webservices\src " />
   </project>
</projects>

Note that the component's src directory is assumed to be underneath the project's srcroot directory.

This is all you really need to get PMDReports up and running, however, there are a few other optional ways you can configure it to get more meaningful data.

If you want to see it in action, skip to the next section, Run.

Custom PMD Rulesets

Optionally but most likely desirably, PMDReports can use custom PMD rulesets to filter out violations for rules that are not deemed important. To do so, configure the rulesets.xml file (located in the root PMDReports directory). By default, PMDReports uses the built-in PMD rulesets, configured in the rulesets.xml file as below:

<?xml version= "1.0 encoding="UTF-8 " ?>
<rulesets>
   <ruleset name= "basic" description= "Basic Rules" />
   <ruleset name= "design" description= "Design Rules" />
   <ruleset name= "strings"
        description= "String and StringBuffer Rulest" />
   <ruleset name= "codesize" description= "Code Size Rules" />
   <ruleset name= "braces" description= "Braces Rules" />
   <ruleset name= "strictexception"
         description= "Strict Exception Rules" />
   <ruleset name= "optimizations"
         description= "Optimization Rules" />
   <ruleset name= "coupling" description= "Coupling Rules" />
   <ruleset name= "naming" description= "naming" />
   <ruleset name= "j2ee" description= "J2EE Rules" />
   <ruleset name= "unusedcode"
         description= "Unused Code Rules" />
</rulesets>

In many cases, it will be desirable to use only a portion of the rules from these rulesets. In these cases, the .xml file ( e.g. naming.xml) from PMD source can be copied and pasted to the PMDREPORTS_HOME/rulesets directory, and the undesirable rules commented out. After this is done, update the rulesets.xml file to use this new configuration file instead. For example, if the naming.xml file was copied, pasted, and modified, the rulesets.xml file would like as below:

<?xml version= "1.0 encoding="UTF-8 " ?>
<rulesets>
   <ruleset name= "basic" description= "Basic Rules" />
   <ruleset name= "design" description= "Design Rules" />
     <ruleset name= "strings"
        description= "String and StringBuffer Rulest" />
   <ruleset name= "codesize" description= "Code Size Rules" />
   <ruleset name= "braces" description= "Braces Rules" />
   <ruleset name= "strictexception"
         description= "Strict Exception Rules" />
   <ruleset name= "optimizations"
         description= "Optimization Rules" />
   <ruleset name= "coupling" description= "Coupling Rules" />
   <ruleset name="naming" description= "naming"
        filename= "rulesets\naming.xml" />
   <ruleset name= "j2ee" description= "J2EE Rules" />
   <ruleset name= "unusedcode" description= "Unused Code Rules" />
</rulesets>

Lastly, upper and lower benchmarks for each ruleset can be defined, so that those components with violations above or below these benchmarks will be displayed in red or green respectively on the Component Comparison Report. To configure these benchmarks, use the minViolations or maxViolations attribute in the ruleset tag, as below:

<?xml version= "1.0 encoding="UTF-8 " ?>
<rulesets>
   <ruleset name= "basic" description="Basic Rules" />
   <ruleset name= "design" description="Design Rules" />
   <ruleset name= "strings"
        description="String and StringBuffer Rulest" />
   <ruleset name= "codesize" description="Code Size Rules" />
   <ruleset name= "braces" description="Braces Rules" />
   <ruleset name= "strictexception"
        description="Strict Exception Rules" />
   <ruleset name= "optimizations"
        description="Optimization Rules" />
   <ruleset name= "coupling"
        description="Coupling Rules" />
   <ruleset name="naming"
      description= "naming"
      filename= "rulesets\naming.xml "
      minViolations="2.00"
      maxViolations="5.00" />
   <ruleset name= "j2ee" description= "J2EE Rules" />
   <ruleset name= "unusedcode" description= "Unused Code Rules" />
</rulesets>

Run

From Windows, either click on the pmdreports.bat file located in the PMDReports root directory or execute this from a DOS prompt. Resulting reports will be saved to the PMDREPORTS_HOME\pmdreports-output\ directory in HTML format.

If you encounter any problems, please ensure:

Also, embarrassingly, the trend graphs look much nicer in Firefox than in IE - so use Firefox for now.

I believe that software development is fundamentally about making decisions, and so this is what I write about (mostly). I've been building software for about 20 years now, as a developer, tech lead, and architect. I have two degrees from Carnegie Mellon University, most recently one in philosophy (thesis here). I live in Pittsburgh, PA with my wife, 3 energetic boys, and dog. Subscribe here or write me at ben dot northrop at gmail dot com.

Got a Comment?


Sign up to hear about the next post!

If you liked this article and want to hear about the next one, enter your email below. I don't spam - you'll only receive an email when there's a new post (which is about once a month, tops). It's all low-key, straight from me.

Comments (0)

 None so far!