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:
- Which components in a project have the best or worst code quality?
- As development continues, is code quality improving? Or getting worse?
- 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 ContentsLastly, 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:
- JRE 1.5 or higher
- WinZip
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 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:
- You are using Java 1.5 or higher.
- Java.exe is in your PATH.
- The projects.xml file has been configured properly.
Also, embarrassingly, the trend graphs look much nicer in Firefox than in IE - so use Firefox for now.
