Choosing which Reports to Include

Author: MJ Carreon

Choosing which reports to include, and which checks to perform during the build, is an important decision that will determine the effectiveness of your build reports. Report results and checks performed should be accurate and conclusive – every developer should know what they mean and how to address them.

Note: In some instances, the performance of your build will be affected by this choice. In particular, the reports that utilize unit tests often have to re-run the tests with new parameters. While future versions of Maven will aim to streamline this, it is recommended that these checks be constrained to the continuous integration and release environments if they cause lengthy builds. See Chapter 7 Team Collaboration with Maven, for more information.

The table below covers the reports discussed in this chapter and reasons to use them. For each report, there is also a note about whether it has an associated visual report (for project site inclusion), and an applicable build check (for testing a certain condition and failing the build if it doesn’t pass).

You can use this table to determine which reports apply to your project specifically and limit your reading to just those relevant sections of the chapter, or you can walk through all of the examples one by one, and look at the output to determine which reports to use.

While these aren’t all the reports available for Maven, the guidelines should help you to determine whether you need to use other reports.

Note: You may notice that many of these tools are Java-centric. While this is certainly the case at present, it is possible in the future that reports for other languages will be available, in addition to the generic reports such as those for dependencies and change tracking.

Table 6-2: Report highlights

Report Description Visual Check Notes
Javadoc Produces an API reference from Javadoc. Yes N/A ✔ Useful for most Java software

✔ Important for any projects publishing a public API
JXR Produces a source cross reference for any Java code. Yes N/A ✔ Companion to Javadoc that shows the source code

✔ Important to include when using other reports that can refer to it, such as Checkstyle

✖ Doesn't handle JDK 5.0 features
Checkstyle Checks your source code against a standard descriptor for formatting issues. Yes Yes ✔ Use to enforce a standard code style.

✔ Recommended to enhance readability of the code.

✖ Not useful if there are a lot of errors to be fixed - it will be slow and the result unhelpful
PMD Checks your source code against known rules for code smells. Yes Yes ✔ Should be used to improve readability and identify simple
and common bugs

✔ Some overlap with Checkstyle rules
CPD Part of PMD, checks for duplicate source code blocks that indicates it was copy/pasted. Yes No ✔ Can be used to identify lazy copy/pasted code that might be
refactored into a shared method

✔ Avoids issues when one piece of code is fixed/updated and the other forgotten
Tag List Simple report on outstanding tasks or other markers in source code Yes No ✔ Useful for tracking TODO items

✔ Very simple, convenient set up

✔ Can be implemented using Checkstyle rules instead
Corbertura Analyze code statement coverage during unit tests or other code execution Yes Yes ✔ Recommended for teams with a focus on tests

✔ Can help identify untested or even unused code

✖ Doesn't identify all missing or inadequate tests, on additional tools may be required
Surefire Report Show the results of unit tests visually Yes Yes ✔ Recommended for easier browsing of results.

✔ Can also show any tests that are long running and slowing the build

✔ Check already performed by surefire:test
Dependency Convergence Examine the state of dependencies in a multiple module build Yes No ✔ Recommended for multiple module builds where consistent versions are important

✔ Can help find snapshots prior to release