Introduction to writing PMD rules

PMD is a framework to perform code analysis. You can create your own rules tocheck for patterns specific to your codebase, or the coding practices of yourteam.

How rules work: the AST

Before running rules, PMD parses the source file into a data structure called anabstract syntax tree (AST).This tree represents the syntactic structure of thecode, and encodes syntactic relations between source code elements. For instance,in Java, method declarations belong to a class: in the AST, the nodes representingmethod declarations will be descendants of a node representing the declaration oftheir enclosing class. This representation is thus much richer than the originalsource code (which, for a program, is just a chain of characters), or the tokenchain produced by a lexer. For example:

classFooextendsObject{}

└─CompilationUnit└─TypeDeclaration└─ClassDeclaration"Foo"├─ModifierList├─ExtendsList│└─ClassType"Object"└─ClassBody

Conceptually, PMD rules work bymatching a “pattern” against the AST of afile.Rules explore the AST and find nodes that satisfy some conditions that are characteristicof the specific thing the rule is trying to flag. Rules then report a violation on these nodes.

Discovering the AST

ASTs are represented by Java classes deriving fromNode.Each PMD language has its own set of such classes, and its own rules about howthese classes relate to one another, based on the grammar of the language. Forexample, all Java AST nodes extendJavaNode.

The structure of the AST can be discovered through

• theRule Designer
• theAST dump feature

Writing new rules

PMD supports two ways to define rules: using anXPath query, or using aJava visitor. XPath rules are much easier to set up, since they’re defineddirectly in your ruleset XML, and are expressive enough for nearly any task.

On the other hand, some parts of PMD’s API are only accessible from Java, e.g.accessing the usages of a declaration. And Java rules allow you to do somecomplicated processing, to which an XPath rule couldn’t scale.

In the end, choosing one strategy or the other depends on the difficulty of whatyour rule does. I’d advise to keep to XPath unless you have no other choice.

Note: Despite that fact, the Java rules are written in Java, any language that PMD supportscan be analyzed. E.g. you can write a Java rule to analyze Apex source code.

XML rule definition

New rules must be declared in a ruleset before they’re referenced. This is thecase for both XPath and Java rules. To do this, therule element is used, butinstead of mentioning theref attribute, it mentions theclass attribute,with the implementation class of your rule.

• For Java rules: this is the concrete class extending AbstractRule (transitively)
• For XPath rules: this isnet.sourceforge.pmd.lang.rule.xpath.XPathRule.
• For XPath rules analyzing XML-based languages: this isnet.sourceforge.pmd.lang.xml.rule.DomXPathRule.SeeXPath rules in XML for more info.

Example for Java rule:

<rulename="MyJavaRule"language="java"message="Violation!"class="com.me.MyJavaRule"><description>        Description</description><priority>3</priority></rule>

Example for XPath rule:

<rulename="MyXPathRule"language="java"message="Violation!"class="net.sourceforge.pmd.lang.rule.xpath.XPathRule"><description>        Description</description><priority>3</priority><properties><propertyname="xpath"><value><![CDATA[//ClassOrInterfaceDeclaration]]></value></property></properties></rule>

Resource index

To learn how to write a rule:

• Your First Ruleintroduces the basic development process of a rule with a running example
• Writing XPath Rulesexplains a bit more about XPath rules and our XPath API
• Writing Java Rulesdescribes how to write a rule in Java

To go further:

• Defining Propertiesdescribes how to make your rules more configurable with rule properties
• Testing your Rules introducesour testing framework and how you can use it to safeguard the quality ofyour rule