"If you cannot measure it, you cannot improve it." -- Lord Calvin
Managing Code Quality with PMDReports
January 4th 2008
If you've used PMD, you know it's a very helpful Java source code analysis tool for improving code quality. Integrated into your IDE, it can point out in real time common stylistic and semantic coding mistakes; things that will, in aggregate, reduce the maintainability, extensibility, or overall quality of the system if not addressed. Even more, it can also be used both as a teacher, disseminating best practices to junior developers, and a code review facilitator, reporting nit-picky "braces and spaces" issues in your teammates' code so you don't have to (which, I'm guessing, is why PMD's motto is "don't shoot the messenger"!).
Essentially, as a developer tool, it's extremely useful. The problem is, however, that as an architectural tool, that is, as a tool that effectively helps stakeholders understand and manage code quality at a system level rather than source code level, PMD alone is fairly powerless. Though it provides excellent, raw code quality data, it has no real mechanism for helping developers and architects understand the bigger picture: is code quality overall improving or degrading, which components in a system have the worst code quality and will therefore be tougher maintain, and how does code quality in our system compare to industry standards.
PMDReports, a simple, open source reporting engine wrapped around PMD, was designed to this end, as a tool to help developers and architects understand and then improve code quality at a system level. Run either manually for a quick quality assessment or hooked into a build and run recurringly, PMDReports will store code quality metrics from PMD in a text-file database, and then aggregate, slice, and dice this data, generating a number of useful HTML reports that illuminate trends in code quality, point out poorly written components, and highlight areas for improvement. Armed with this information, architects can make better decisions regarding process, policy, and design.
The 5 Minute Test Drive
Ok, enough talk, let's see it in action! Getting PMDReports up and running is extremely easy:
- Download the most recent version of PMDReports here.
- Unzip the bundle to any directory, like
- Run PMDReports either from a MS-DOS prompt or from windows by executing the pmdreports.bat file. This will create a directory called "pmdreports-output".
- Open in a web browser any of the .html files in the
PMDReports is configured out of the box to run on itself, and so these reports show code quality statistics at a snapshot in time (i.e. the date you ran it) for the PMDReports source code. Because on the initial run PMDReports has only one day worth of data, any trend reports will not be available. To see the real value of PMDReports, it needs to be run periodically on a changing code base, and so the next section will help get PMDReports set up for your own project.
Configuring PMDReports for your Project
PMDReports requires only one simple configuration file to be setup, projects.xml. This file defines which components will be analyzed by PMDReports, and where the source code for these components is located. Below is a sample projects.xml file.
<?xml version= "1.0" encoding= "UTF-8"?>
<project name="AbcProj" srcroot="C:\projects\abcproj" >
<component name="Manager" src="\manager\src " />
<component name="Web Services" src="\webservices\src " />
Note that one project can contain one or many projects, and that the component
src directory starts from the project's
srcroot, so for example the ABC Project's Manager component starts at
C:\projects\abcproj\manager\src. Also note that any number of projects or components can be defined in PMDReports - so for example it's possible to analyze a project with, say, 40 unique components.
At this point, PMDReports can be re-run, and will generate statistics for the project configured in the projects.xml file. To do so, from an MS-DOS prompt run
pmdreports.bat using the
outputDir flag to store the reports in a new directory:
C:\PMDReports\>pmdreports.bat –outputDir .\test_output\
Now check the
test_output directory for the reports. Again, because PMDReports has only one days worth of data, none of the trend reports will be available. Even with just the snapshot reports, however, PMDReports can still help you understand which components have more or less code quality violations and which violations are most prevelant.
Next week I'll post again and get into some more advanced features of PMDReports, like customizing rulesets, hooking PMDReports into an Ant build, and analyzing trend reports. Stay tuned...
I believe that software development is fundamentally about making decisions, and so this is what I write about (mostly).
I'm a Distinguished Technical Consultant for Summa and 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 at summa-tech dot com.