Managing Code Quality with PMDReports

"If you cannot measure it, you cannot improve it." -- Lord Calvin

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 C:\PMDReports.
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_HOME>/pmdreports-output directory.

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"?> 

	    <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 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...