Checkstyle Configuration

Overview

A Checkstyle configuration specifies which modules to plug in and apply to Java source files. Modules are structured in a tree whose root is the Checker module. The next level of modules contains FileSetChecks- modules that take a set of input files and fire error messages. Many checks are submodules of the TreeWalker FileSetCheck module. The TreeWalker operates by separately transforming each of the Java source files into an abstract syntax tree and then handing the result over to each of its submodules which in turn have a look at certain aspects of the tree.

Checkstyle obtains a configuration from an XML document whose elements specify the configuration's hierarchy of modules and their properties. You provide a file that contains the configuration document when you invoke Checkstyle at the command line, and when you run a Checkstyle task in ant.

Modules

A module element in the configuration XML document specifies a module identified by the element's name attribute.

Here is a fragment of a typical configuration document:

<module name="Checker">
    <module name="PackageHtml"/>
    <module name="TreeWalker">
        <module name="AvoidStarImport"/>
        <module name="ConstantName"/>
        <module name="EmptyBlock"/>
    </module>
</module>

In this configuration:

Root module Checker has child FileSetChecks PackageHtml and TreeWalker. (Module PackageHtml checks that all packages have package documentation.)
Module TreeWalker has submodules AvoidStarImport, ConstantName, and EmptyBlock. (Modules AvoidStarImport, ConstantName, and EmptyBlock check that a Java source file has no star imports, has valid constant names, and has no empty blocks, respectively.)

For each configuration module, Checkstyle loads a class identified by the name attribute of the module. There are several rules for loading a module's class:

Load a class directly according to a package-qualified name, such as loading class com.puppycrawl.tools.checkstyle.TreeWalker for element
```
    <module name="com.puppycrawl.tools.checkstyle.TreeWalker">
          
```
This is useful for plugging third-party modules into a configuration.
Load a class of a pre-specified package, such as loading class com.puppycrawl.tools.checkstyle.checks.AvoidStarImport for element
```
        <module name="AvoidStarImport"/>
          
```
Checkstyle applies packages com.puppycrawl.tools.checkstyle and com.puppycrawl.tools.checkstyle.checks by default. You can also specify packages when you invoke Checkstyle at the command line, and when you run a Checkstyle task in ant.
Apply the above rules to name concatenated with "Check", such as loading class com.puppycrawl.tools.checkstyle.checks.ConstantNameCheck for element
```
        <module name="ConstantName"/>
          
```

Properties

Properties of a module control how the module performs its checks. Each module property has a default value, and you are not required to define a property in the configuration document if the default value is satisfactory. To assign a non-default value to a module's property, define a child property element of the module element in the configuration XML document. Also provide appropriate name and value attributes for the property element. For example, property max of module MethodLength specifies the maximum allowable number of lines in a method or constructor, and has default value 150. Here is a configuration of module MethodLength so that the check reports methods and constructors with more than 60 lines:

      
        <module name="MethodLength">
            <property name="max" value="60"/>
        </module>

Command line properties and ant Checkstyle task properties apply to the root Checker module. Also, properties are inherited in the module hierarchy. These features make it easy to define one property value that applies to many modules. For example, the following configuration fragment specifies that a tabWidth of 4 applies to all FileSetChecks and their submodules:

<module name="Checker">
    <property name="tabWidth" value="4"/>
    <module name="PackageHtml"/>
    <module name="TreeWalker">
        <module name="AvoidStarImport"/>
        <module name="ConstantName"/>
        ...
    </module>
</module>

The value of a module property can be specified through property expansion with the ${property_name} notation, where property_name is a command line property or an ant Checkstyle task property. For example, the following configuration document element gives property headerFile the value of command line property checkstyle.header.file:

      <property name="headerFile" value="${checkstyle.header.file}"/>

You can use property expansion to re-specify a module property value without changing the configuration document.

TreeWalker Checks

The TreeWalker module creates a syntax tree for a Java source file and invokes its submodules, called Checks, during a walk, or traversal, of the nodes of the tree. Every node of the syntax tree has a token. A visit to a node during the traversal triggers all Checks that are configured for its token. For example, if Check MethodLength has been configured as a submodule of TreeWalker, then a visit to a node with a method or a constructor definition token triggers MethodLength to check the number of lines of the node's code block.

Some Checks, such as FileLength and LineLength, apply directly to the source file and do not involve tokens of the syntax tree. Other Checks are associated with configurable sets of tokens that trigger the Checks. For example, this element configures Check MethodLength:

    <module name="MethodLength"/>

The default token set for MethodLength is {METHOD_DEF, CTOR_DEF}, method definition and constructor definition tokens, so TreeWalker invokes MethodLength whenever it visits a node with a METHOD_DEF or a CTOR_DEF token.

You specify the trigger tokens for a Check with property tokens. The value of tokens is a list that denotes a subset of the Check's tokens, as in the following element that configures Check MethodLength to check the number of lines of methods only:

        <module name="MethodLength">
            <property name="tokens" value="METHOD_DEF"/>
        </module>

To apply particular properties to different subsets of tokens for a Check, repeat the Check. For example, to check that the length of each method is at most 150 lines (the default value of MethodLength property max) and the length of each constructor is at most 60 lines, include the following in the TreeWalker configuration:

        <module name="MethodLength">
            <property name="tokens" value="METHOD_DEF"/>
        </module>

        <module name="MethodLength">
            <property name="tokens" value="CTOR_DEF"/>
            <property name="max" value="60"/>
        </module>

Configurations of the Checks are specified in the following pages:

XML Details

The following is a DTD for a configuration XML document specifies the hierarchy of modules and their properties:

<?xml version="1.0" encoding="UTF-8"?>

<!ELEMENT module (module|property)*>
<!ATTLIST module name NMTOKEN #REQUIRED>

<!ELEMENT property EMPTY>
<!ATTLIST property
	name NMTOKEN #REQUIRED
	value CDATA #REQUIRED
>

Checkstyle validates a configuration XML document when it loads the document. To validate against the above configuration DTD, include the following document type declaration in your configuration XML document:

    <!DOCTYPE module PUBLIC
    "-//Puppy Crawl//DTD Check Configuration 1.0//EN"
    "http://www.puppycrawl.com/dtds/configuration_1_0.dtd">

Checkstyle also strictly enforces the encoding attribute of an XML declaration. If Checkstyle rejects your configuration document's encoding, correct the value of the encoding attribute, or remove the echoing attribute entirely.

For a complete example of a configuration XML document, examine file docs/checkstyle_checks.xml that the Checkstyle team uses to validate the Checkstyle source code.