4.4. PMD Rules and Warnings

PMD has a very large list of rules that it uses to check your source code. There are a great many rules, so not everybody is likely to agree with all of them. But as the user, you have the ultimate say over which rules are run. You can enable/disable particular sets of rules, as mentioned briefly under command-line usage earlier. Or you can change your code to avoid certain warnings.

You can disable warnings within your code in two ways:

• Use a special comment marker, which defaults to NOPMD.

• Use a Java 5 @SuppressWarnings annotation.

The PMD comment marker goes at the start of a comment on the same line as the construct that would trigger the error and suppresses all PMD warnings for that line. For example, PMD has a rule that warns about non-final variables with all-upper-case names, since these are conventionally used only for constants. To stop this warning, add the NOPMD comment:

     public static String MESSAGE1 = "Hello";     // NOPMD


     @SuppressWarnings("PMD.SuspiciousConstantFieldName")
     public static String MESSAGE2 = "Hello";

The hard part of using this more selective elimination of messages is knowing the PMD name for the message. Unlike FindBugs, PMD doesn't print the name of the message-causing rule in the message. My technique for finding it is:

Click on the Violations Outline (this view is shown by default in the PMD perspective in Eclipse);

The @SuppressWarnings annotation (class java.lang.SuppressWarnings) is a standard Java 5 mechanism for telling the compiler that given classes, methods, fields, and the like should not have certain compiler warnings emitted. The inventors of this annotation wisely made the details of it an extensible, comma-separated list of warnings to be suppressed on the given Java elements. To deal with the issue of naming collisions between different tools vendors, Sun's Java documentation for this annotation (http://java.sun.com/javase/6/docs/api/java/lang/SuppressWarnings.html) states that "Compiler vendors should document the warning names they support in conjunction with this annotation type. They are encouraged to cooperate to ensure that the same names work across multiple compilers." Despite this, the PMD project uses warning names that begin with "PMD.", which at least does not conflict with those of any other tools vendor. As mentioned, the project also maintains their complete list of rules online (http://pmd.sourceforge.net/rules/index.html). Here's an example of using this annotation:

One little annoyance left, and that is that Eclipse will by default warn about these non-warning requests :-), since it doesn't recognize the warning suppression values that begin with PMD. Fortunately you can turn off this "warning warning" by going into Project Properties → Java Compiler → Errors/Warnings, select Annotations, and set Unhandled warning token in @SuppressWarnings to Ignore.

Within the IDE you can also enable or disable rules for all files in the project, either individually or by using a project rules file. In some projects I have a lot of self-contained demo programs that use the System.out.print methods, since it's not worth configuring a "logger" (see Recipes 17.8 and 17.9 in the Java Cookbook (http://javacook.darwinsys.com) for information on two popular loggers, log4j (http://logging.apache.org/log4j) and java.util.logging (http://java.sun.com/javase/6/docs/api/java/util/logging)). Yet PMD by default considers any use of System.out.print methods as an error, not a warning. It turns my project red merely because I had the temerity to use System.out. The nerve of some people! However, there is an easy fix. In the PMD project pane, as before, simply find the offending rule, click its checkbox off, and you're done (see "Figure 4-2").

Figure 4-2. Disabling System.out.print errors

As the last checkbox in "Figure 4-2" shows, you can also use a "project rules file." This is in the same format as the existing rules files, and lists the rules and their details. I have not found this option very useful as it requires repeating information that is already in the standard rules files; in fact, if you check this checkbox and don't already have a rules file (named .rules) in your Eclipse project directory, PMD will offer to create this file, containing all the information from the predefined rules files included in PMD, for all the rules you have selected (hopefully a future version will provide an "include files" mechanism). You can then use this same file in your Ant build to batch-check the project with the same set of rules that is used by the developers in the IDE. See "Section 4.6" later for more information on the rules file format.