Checkstyle Configuration
This task runs Checkstyle over specified Java files. The task has been tested using ANT 1.5. -The latest version of checkstyle can be found at http://checkstyle.sourceforge.net/. -This task is included in the checkstyle distribution.
- -The easiest way is to include checkstyle-all-@CHECKSTYLE_VERSION@.jar in the classpath. This contains all the classes required to run Checkstyle. Alternatively, you must include the following in the classpath:
-To use the task in a build file, you will need the following
-taskdef declaration:
- <taskdef resource="checkstyletask.properties" - classpath="/path/to/checkstyle-all-@CHECKSTYLE_VERSION@.jar"/> -- - -
Or, assuming that Checkstyle is in the global classpath (not recommended),
-then you will need the following taskdef declaration:
- <taskdef resource="checkstyletask.properties"/> -- - -
| Attribute | -Description | -Required | -
| file | -File to run checkstyle on. | -One of either file or at least one nested fileset element | -
| config | -Specifies a file that defines the configuration modules. - See here for a description of how to define a configuration. | -Exactly one of config or configURL | -
| configURL | -Specifies a URL that defines the configuration modules. - See here for a description of how to define a configuration. | -Exactly one of config or configURL | -
| properties | -- Specifies a file that contains properties for - expanded property values of the configuration. - Ant properties (like ${basedir}) and nested property elements override - the properties in this file. - | -No | -
| packageNamesFile | -- Specifies a file that contains - package names for the configuration. - | -No | -
| failOnViolation | -Specifies whether the build will continue even if there are violations. - Defaults to "true". | -No | -
| failureProperty | -The name of a property to set in the event of a violation. | -No | -
| maxErrors | -The maximum number of errors that are tolerated before breaking - the build or setting the failure property. Defaults to - "0". | -No | -
| maxWarnings | -The maximum number of warnings that are tolerated before breaking - the build or setting the failure property. Defaults to - "2147483647", i.e. - Integer.MAX_VALUE. | -No | -
| classpath | -The classpath to use when looking up classes. Defaults to the current classpath. | -No | -
| classpathref | -The classpath to use when looking up classes, given as a reference - to a path defined elsewhere. | -No | -
This task supports the nested elements -<fileset>, -<classpath>, -<formatter>, and -<property>.
- -The parameters for the <formatter> element are:
- -| Attribute | -Description | -Required | -
| type | -
- The type of output to generate. The valid values are: -
Defaults to "plain". - |
- No | -
| toFile | -The file to write output to. Defaults to standard output. Note, there is no way to explicitly specify standard output. - | -No | -
A <property> element provides a property for -expanded property values of the configuration. -The parameters for the <property> element are:
- -| Attribute | -Description | -Required | -
| key | -The key for the property. |
- Yes | -
| value | -The value of the property specified as a string. | -Either value or file | -
| file | -The value of the property specified as a file. This is - great for specifying file names relative to the ANT build file. | -Either value or file | -
Run checkstyle with configuration file docs/sun_checks.xml on a single file
- <checkstyle config="docs/sun_checks.xml" file="Check.java"/> -- -
Run checkstyle on a set of Java files using site-wide configuration and -an expanded property value
-- <checkstyle config="/path/to/site/sun_checks.xml"> - <fileset dir="src/checkstyle" includes="**/*.java"/> - - <!-- Location of cache-file. Something that is project specific --> - <property key="checkstyle.cache.file" file="target/cachefile"/> - </checkstyle> -- -
Run checkstyle on a set of files and output messages to standard output in plain format, and a file in XML format
-- <checkstyle config="docs/sun_checks.xml"> - <fileset dir="src/checkstyle" includes="**/*.java"/> - <formatter type="plain"/> - <formatter type="xml" toFile="build/checkstyle_errors.xml"/> - </checkstyle> --
-Run checkstyle with configuration file docs/sun_checks.xml on a file and
-provide a package names file
-
- <checkstyle config="docs/sun_checks.xml" - packageNamesFile="myPackageNames.xml" - file="Check.java"/> -- -
- -
Run checkstyle in an automated build and send an email report if style violations are detected
-
- <target name="checkstyle"
- description="Generates a report of code convention violations.">
-
- <checkstyle config="docs/sun_checks.xml"
- failureProperty="checkstyle.failure"
- failOnViolation="false">
- <formatter type="xml" tofile="checkstyle_report.xml"/>
- <fileset dir="src" includes="**/*.java"/>
- </checkstyle>
-
- <style in="checkstyle_report.xml" out="checkstyle_report.html" style="checkstyle.xsl"/>
-
- </target>
-
- <!-- run this target as part of automated build -->
- <target name="checkstyle-nightly"
- depends="checkstyle"
- if="checkstyle.failure"
- description="Sends email if checkstyle detected code conventions violations.">
-
- <!-- use your own server and email addresses below. See Ant documentation for details -->
-
- <mail from="qa@some.domain"
- tolist="someone@some.domain,someoneelse@some.domain"
- mailhost="mailbox.some.domain"
- subject="Checkstyle violation(s) in project ${ant.project.name}"
- files="checkstyle_report.html"/>
-
- </target>
-
-
-Copyright © 2002-2004 Oliver Burn. All rights Reserved.
- - diff --git a/docs/api/.cvsignore b/docs/api/.cvsignore deleted file mode 100644 index 905a3f203..000000000 --- a/docs/api/.cvsignore +++ /dev/null @@ -1,4 +0,0 @@ -com -*.html -*.css -package-list diff --git a/docs/checkstyle_checks.xml b/docs/checkstyle_checks.xml deleted file mode 100644 index ded2885ec..000000000 --- a/docs/checkstyle_checks.xml +++ /dev/null @@ -1,137 +0,0 @@ - - - --This document describes how to run checkstyle using the command line tool. The -latest version of checkstyle can be found at http://checkstyle.sourceforge.net. -This command line tool is included in the checkstyle distribution. -
- - --The easiest way is to include checkstyle-all-@CHECKSTYLE_VERSION@.jar in the classpath. If you are running JDK 1.4 this contains all the classes required to run checkstyle (JDK 1.3 users must add a JAXP compliant XML parser implementation). Alternatively, you must include the following in the classpath: -
--The command line usage is: -
-- java -D<property>=<value> \ - com.puppycrawl.tools.checkstyle.Main \ - -c <configurationFile> [-n <packageNameFile>] \ - [-f <format>] [-p <propertiesFile>] [-o <file>] \ - [-r <dir>] file... -- -
-Checkstyle will process the specified files and by default report errors to -standard out in plain format. Checkstyle requires a configuration XML file that configures the -checks to apply. Command line options are: -
- -
-Set the properties for expanded property values
-by either by assigning system
-properties using the -D<property>=<value> arguments to
-java or specifying a property file using the -p option.
-If a property file is specified, the system properties are ignored.
-
-Run checkstyle with configuration file docs/sun_checks.xml on a file
-
- java com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml \ - Check.java -- -
-Run checkstyle with configuration file docs/sun_checks.xml
-on all java files in a directory
-
- java com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml \ - -r src/ -- -
-Run checkstyle with configuration file docs/sun_checks.xml
-on a file and provide a system property
-
- java -Dcheckstyle.cache.file=target/cachefile \ - com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml \ - Check.java -- -
-Run checkstyle with configuration file docs/sun_checks.xml
-on a file and use properties in a file
-
- java com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml \ - -p myCheckstyle.properties Check.java -- -
-Run checkstyle with configuration file docs/sun_checks.xml
-on a file and output to a file in XML format
-
- java com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml \ - -f xml -o build/checkstyle_errors.xml Check.java -- -
-Run checkstyle with configuration file docs/sun_checks.xml on a file and
-provide a package names file
-
- java com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml \ - -n myPackageNames.xml Check.java -- - -
- It is possible to run Checkstyle directly from the JAR file using the - -jar option. An example would be: -
- -- java -jar checkstyle-all-@CHECKSTYLE_VERSION@.jar \ - -c docs/sun_checks.xml Check.java --
Copyright © 2002-2004 Oliver Burn. All rights Reserved.
- - diff --git a/docs/config.html b/docs/config.html deleted file mode 100644 index baa7d575c..000000000 --- a/docs/config.html +++ /dev/null @@ -1,992 +0,0 @@ - - - - -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 - -
- 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. The documentation directory of the Checkstyle distribution contains - a sample configuration file sun_checks.xml which configures Checkstyle - to check for the Sun coding conventions. - -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: - -
- 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: - -
Properties-- Properties of a module control how the module performs its task. - 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 - TreeWalker and its submodules: - --<module name="Checker"> - <module name="PackageHtml"/> - <module name="TreeWalker"> - <property name="tabWidth" value="4"/> - <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. - -- The property element provides an optional default attribute which is used - when a property in the value cannot be resolved. For example this configuration - snippet from a central configuration file checks that methods have javadoc, but - allows inividual projects to override the severity by specifying - their desired value in the command line property - checkstyle.javadoc.severity: - -
- <module name="JavaDocMethod">
- <property name="severity" value="${checkstyle.javadoc.severity}" default="error"/>
- </module/>
-
- - This feature is a great help when setting up a centralized configuration file - (e.g. one file for the whole company) to lower configuration maintenance costs. - Projects that are happy with the default can simply use that configuration file as is, - but individual projects with special needs have the fexibility to adjust a few - settings to fit their needs without having to copy and maintain the whole configuration. - -Checker-- All configurations have root module Checker. - Checker contains - -
Properties-
- For example, the following configuration fragment specifies base directory - src/checkstyle and German locale for all modules: - --<module name="Checker"> - <property name="basedir" value="src/checkstyle"/> - <property name="localeCountry" value="DE"/> - <property name="localeLanguage" value="de"/> - <module name="PackageHtml"/> - <module name="TreeWalker"> - ... - </module> -</module> -- TreeWalker-- FileSetCheck TreeWalker checks individual Java source files - and defines properties that are applicable to checking such files. - -Properties-
- For example, the following configuration fragment specifies TreeWalker - cache file target/cachefile, and a tabWidth - of 4: - --<module name="Checker"> - <module name="TreeWalker"> - <property name="cacheFile" value="target/cachefile"/> - <property name="tabWidth" value="4"/> - ... - </module> -</module> -- - To configure a TreeWalker so that it handles files with the UTF-8 - charset: - --<module name="Checker"> - <module name="TreeWalker"> - <property name="charset" value="UTF-8"/> - ... - </module> -</module> -- - - - To integrate Checkstyle with BEA Weblogic Workshop 8.1: - - --<module name="Checker"> - <module name="TreeWalker"> - <property name="fileExtensions" value="java,ejb,jpf"/> - ... -- - 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: - - -
Severity-- Each check has a severity property - that a Checkstyle audit assigns to all violations of the check. The default severity level of - a check is error. - -- You can use the severity property to control the output of the plain formatter for the command - line tool and the ANT task. The plain formatter does not report violations with severity level - ignore, and notes violations with severity level - warning. For example, according to the following configuration fragment, - the plain formatter outputs warnings for translation violations: - -- <module name="Translation"> - <property name="severity" value="warning"/> - </module> -- - The XML formatter reports the severity level - of every violation as an attribute of the violation's error - element. - - - -Filters-- A Checker module has a set of Filter submodules to filter audit events, including the error messages fired by Checks. - A Filter can accept or reject an audit event. If all Filters accept - an audit event, then the Checker reports the event. - If any Filter rejects an event, then the Checker does not report the event. -- Filter SeverityMatchFilter decides audit events according to the - severity level of the event. - -SeverityMatchFilter Properties-
- For example, the following configuration fragment directs the Checker to not report audit events with severity level - info: - - -- <module name="SeverityMatchFilter"> - <property name="severity" value="info"/> - <property name="acceptOnMatch" value="false"/> - </module> -- - - Filter SuppressionFilter rejects audit events for Check errors according to a - suppressions XML document in a file. If there is no configured suppressions file, the - Filter accepts all audit events. - - -SuppressionFilter Properties-
- For example, the following configuration fragment directs the Checker to use a SuppressionFilter - with suppressions file docs/suppressions.xml: - - -- <module name="SuppressionFilter"> - <property name="file" value="docs/suppressions.xml"/> - </module> -- - - A suppressions XML document contains a set of suppress elements, - where each suppress element - has a files attribute, a checks attribute, - an optional lines attribute, and an optional - columns attribute. - Attributes files and checks are - regular expressions. - Attributes lines and columns are - comma-separated values, where each value is an integer or - a range of integers denoted by integer-integer. - -- An audit event for a Check error matches a suppress element if - the file name for the event matches the files attribute of the element, - the name of the Check matches the checks attribute, and - the line of the event matches the lines attribute (provided the attribute exists) or - the column of the event matches the columns attribute (provided the attribute exists). - When a SuppressionFilter decides an audit event for a Check error, it rejects - the event if the event matches any one of the configured suppress elements. In all other - cases, the Filter accepts the event. - - -- For example, the following suppressions XML document directs a SuppressionFilter - to reject JavadocStyleCheck errors for lines 82 and 108 to 122 of file - AbstractComplexityCheck.java, and - MagicNumberCheck errors for line 221 of file - JavadocStyleCheck.java: - --<?xml version="1.0"?> - -<!DOCTYPE suppressions PUBLIC - "-//Puppy Crawl//DTD Suppressions 1.0//EN" - "http://www.puppycrawl.com/dtds/suppressions_1_0.dtd"> - -<suppressions> - <suppress checks="JavadocStyleCheck" - files="AbstractComplexityCheck.java" - lines="82,108-122"/> - <suppress checks="MagicNumberCheck" - files="JavadocStyleCheck.java" - lines="221"/> -</suppressions> -- - - Filter SuppressionCommentFilter uses - pairs of comments to suppress audit events. - -- Rationale: Sometimes there are legitimate reasons for violating - a check. When this is a matter of the code in question and not - personal preference, the best place to override the policy is in - the code itself. Semi-structured comments can be associated - with the check. This is sometimes superior to a separate - suppressions file, which must be kept up-to-date as the source - file is edited. - -- Usage: This filter only works in conjunction with a - FileContentsHolder, since that check makes the suppression - comments in the .java files available sub rosa. A configuration - that includes this filter must configure FileContentsHolder - as a child module of TreeWalker. - -SuppressionCommentFilter Properties-
Restrictions-- offCommentFormat and onCommentFormat must have equal - paren counts. - -Examples-- To configure the check that makes comments available to the filter: - --<module name="TreeWalker"> - ... - <module name="FileContentsHolder"/> - ... -</module> --
- To configure a filter to suppress audit events between a
- comment containing -<module name="SuppressionCommentFilter"/> -- -
- To configure a filter to suppress audit events between a
- comment containing line -<module name="SuppressionCommentFilter"> - <property name="offCommentFormat" value="BEGIN GENERATED CODE"/> - <property name="onCommentFormat" value="END GENERATED CODE"/> -</module> -- -
- To configure a filter so that -<module name="SuppressionCommentFilter"> - <property name="offCommentFormat" value="stop constant check"/> - <property name="onCommentFormat" value="resume constant check"/> - <property name="checkFormat" value="ConstantNameCheck"/> -</module> --
- To configure a filter so that -<module name="SuppressionCommentFilter"> - <property name="offCommentFormat" value="UNUSED OFF\: (\w+)"/> - <property name="onCommentFormat" value="UNUSED ON\: (\w+)"/> - <property name="checkFormat" value="Unused"/> - <property name="messageFormat" value="^Unused \w+ '$1'.$"/> -</module> --
- To configure a filter so that -<module name="SuppressionCommentFilter"> - <property name="offCommentFormat" value="CSOFF\: ([\w\|]+)"/> - <property name="onCommentFormat" value="CSON\: ([\w\|]+)"/> - <property name="checkFormat" value="$1"/> -</module> -- - - AuditListeners-- In addition to an audit reporter for text or XML output, a Checker can have - custom AuditListeners - that handle audit events. In order to use a custom listener, add a Checker - submodule for the listener and its properties. - For example, to configure a Checker - so that it uses custom listener VerboseListener to print audit messages - to a file named "audit.txt", include the following module in the - configuration file: - - -- <module name="com.mycompany.listeners.VerboseListener"> - <property name="file" value="audit.txt"/> - </module> -- - - - - Packages-- Checkstyle loads a module class according to the name - of a module element, and automatically appends pre-specified - package prefixes to that name in its search for a loadable class. - By default, Checkstyle applies packages - com.puppycrawl.tools.checkstyle, - com.puppycrawl.tools.checkstyle.filters, and - com.puppycrawl.tools.checkstyle.checks as well as any sub-packages of - com.puppycrawl.tools.checkstyle.checks that are - distributed with Checkstyle. To specify other packages to apply, - create a package names XML document in a file, and provide that file as a - command line option or as a - attribute of an ant Checkstyle task. - This is useful for integrating other modules in your configuration. - -- A package names XML document specifies a list of package names. Here is a - sample package names XML document for packages - com.puppycrawl.tools.checkstyle and - com.puppycrawl.tools.checkstyle.checks: - --<checkstyle-packages> - <package name="com.puppycrawl.tools.checkstyle"> - <package name="checks"/> - </package> -</checkstyle-packages> -- - Notice that the packages are specified recursively - a child - package element is - a subpackage of its parent package element. - -- For example, to incorporate modules from package com.mycompany.checks - with Checkstyle modules, create the XML file below and specify that file as a - command line option or as a - attribute of an ant Checkstyle task.: - --<?xml version="1.0" encoding="UTF-8"?> - - <!DOCTYPE checkstyle-packages PUBLIC - "-//Puppy Crawl//DTD Package Names 1.0//EN" - "http://www.puppycrawl.com/dtds/packages_1_0.dtd"> - -<checkstyle-packages> - <package name="com.mycompany.checks"> - <package name="com.puppycrawl.tools.checkstyle"> - <package name="checks"> - <package name="blocks"/> - <package name="coding"/> - <package name="design"/> - <package name="imports"/> - <package name="indentation"/> - <package name="j2ee"/> - <package name="javadoc"/> - <package name="metrics"/> - <package name="naming"/> - <package name="sizes"/> - <package name="whitespace"/> - </package> - <package name="filters"/> - </package> -</checkstyle-packages> -- - Now you can configure a module of package com.mycompany.checks, - say com.mycompany.checks.MethodLimitCheck, with a shortened - module element in the configuration document: - -- <module name="MethodLimit"/> --
-
-
- Important- - If you provide a package names XML document for your own modules and still need to use - Checkstyle modules, you must include package elements for - Checkstyle's packages. -XML Details-Configuration XML Document-- The following 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.2//EN" - "http://www.puppycrawl.com/dtds/configuration_1_2.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 encoding attribute entirely. - -- For a complete example of a configuration XML document, examine file docs/sun_checks.xml - that checks the Sun coding conventions. - -Package Names XML Document-- This is a DTD for a package names XML document: - --<?xml version="1.0" encoding="UTF-8"?> - -<!ELEMENT checkstyle-packages (package)*> - -<!ELEMENT package (package)*> -<!ATTLIST package name NMTOKEN #REQUIRED> -- - Checkstyle also validates a package names XML document when it loads the document. - To validate against the above package names DTD, - include the following document type declaration in - your package names XML document: - -- <!DOCTYPE checkstyle-packages PUBLIC - "-//Puppy Crawl//DTD Package Names 1.0//EN" - "http://www.puppycrawl.com/dtds/packages_1_0.dtd"> -- - - Suppressions XML Document-- This is a DTD for a suppressions XML document: - --<?xml version="1.0" encoding="UTF-8"?> - -<!ELEMENT suppressions (suppress*)> - -<!ELEMENT suppress EMPTY> -<!ATTLIST suppress files CDATA #REQUIRED - checks CDATA #REQUIRED - lines CDATA #IMPLIED - columns CDATA #IMPLIED> -- |
-
-Copyright © 2002-2004 Oliver Burn. All rights Reserved. -
- - - \ No newline at end of file diff --git a/docs/config_blocks.html b/docs/config_blocks.html deleted file mode 100644 index ba28c3b94..000000000 --- a/docs/config_blocks.html +++ /dev/null @@ -1,437 +0,0 @@ - - - - -Checks for blocks |
- |
-
-
|
-
- EmptyBlock-Description-- Checks for empty blocks. - -Properties-
Examples-- To configure the check: - --<module name="EmptyBlock"/> -- - To configure the check for the text policy and only - catch blocks: - --<module name="EmptyBlock"> - <property name="option" value="text"/> - <property name="tokens" value="LITERAL_CATCH"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.blocks - -Parent Module-- TreeWalker - -LeftCurlyDescription-- Checks for the placement of left curly braces ('{') for code blocks. - The policy to verify is specified using property option. - Policies eol and - nlow take into account property maxLineLength. - -Properties-
Examples-- To configure the check: - --<module name="LeftCurly"/> -- - To configure the check to apply the nl policy to type blocks: - --<module name="LeftCurly"> - <property name="option" value="nl"/> - <property name="tokens" value="CLASS_DEF,INTERFACE_DEF"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.blocks - -Parent Module-- TreeWalker - -NeedBracesDescription-- Checks for braces around code blocks. - -Properties-
Examples-- To configure the check: - --<module name="NeedBraces"/> -- - To configure the check for if and - else blocks: - --<module name="NeedBraces"> - <property name="tokens" value="LITERAL_IF, LITERAL_ELSE"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.blocks - -Parent Module-- TreeWalker - -RightCurlyDescription-- Checks the placement of right curly braces ('}') for - else, try, and catch - tokens. The policy to verify is specified using property - option. - -Properties-
Examples-- To configure the check: - --<module name="RightCurly"/> -- - To configure the check with policy alone for - else tokens: - --<module name="RightCurly"> - <property name="option" value="alone"/> - <property name="tokens" value="LITERAL_ELSE"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.blocks - -Parent Module-- TreeWalker - - -AvoidNestedBlocksDescription-- Finds nested blocks, i.e. blocks that are used freely in the code. - - Rationale: Nested blocks are often leftovers from the debugging process, - they confuse the reader. - - -- For example this Check finds the obsolete braces in - -
- public void guessTheOutput()
- {
- int whichIsWich = 0;
- {
- int whichIsWhich = 2;
- }
- System.out.println("value = " + whichIsWhich);
- }
-
- - and debugging / refactoring leftovers such as - - -
-// if (conditionThatIsNotUsedAnyLonger)
-{
- System.out.println("unconditional");
-}
-
-
- - A case in a switch statement does not implicitly form a block. - Thus to be able to introduce local variables that have case scope - it is necessary to open a nested block. This is supported, set - the allowInSwitchCase property to true and include all statements - of the case in the block. - - -
-switch (a)
-{
- case 0:
- // Never OK, break outside block
- {
- x = 1;
- }
- break;
- case 1:
- // Never OK, statement outside block
- System.out.println("Hello");
- {
- x = 2;
- break;
- }
- case 1:
- // OK if allowInSwitchCase is true
- {
- System.out.println("Hello");
- x = 2;
- break;
- }
-}
-
-
-
- Properties-
Examples-- To configure the check: - --<module name="AvoidNestedBlocks"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.blocks - -Parent Module-- TreeWalker - - - |
-
-Copyright © 2002-2004 Oliver Burn. All rights Reserved. -
- - - diff --git a/docs/config_coding.html b/docs/config_coding.html deleted file mode 100644 index 1fe583e45..000000000 --- a/docs/config_coding.html +++ /dev/null @@ -1,1724 +0,0 @@ - - - - -Checks for Coding problems |
- |
-
-
|
-
-
-
- ArrayTrailingCommaDescription-- Checks that array initialization contains a trailing comma. - -
- int[] a = new int[]
- {
- 1,
- 2,
- 3,
- };
-
- - The check allows to not add a comma if both left and right curlys - are on the same line. - -
- return new int[] { 0 };
-
- - Rationale: Putting this comma in makes it easier to change the - order of the elements or add new elements on the end. - -Examples-- To configure the check: - --<module name="ArrayTrailingComma"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -AvoidInlineConditionalsDescription-- Detects inline conditionals. - - An example inline conditional is this: - -
-String a = getParameter("a");
-String b = (a==null || a.length<1) ? null : a.substring(1);
-
- - Rationale: Some developers find inline conditionals hard to read, - so their company's coding standards forbids them. - -Examples-- To configure the check: - --<module name="AvoidInlineConditionals"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - - -CovariantEquals-Description-- Checks that classes that define a covariant equals() - method also override method equals(java.lang.Object). - Inspired by findbugs. - -- Rationale: Mistakenly defining a covariant equals() - method without overriding method equals(java.lang.Object) - can produce unexpected runtime behaviour. - - -Example-- To configure the check: - --<module name="CovariantEquals"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -DoubleCheckedLockingDescription-- The "double-checked locking" idiom (DCL) tries to avoid the runtime cost - of synchronization. An example that uses the DCL idiom is this: - -
-public class MySingleton
-{
- private static theInstance = null;
-
- private MySingleton() {}
-
- public MySingleton getInstance() {
- if ( theInstance == null ) { // synchronize only if necessary
- synchronized( MySingleton.class ) {
- if ( theInstance == null ) {
- theInstance = new MySingleton();
- }
- }
- }
- }
-}
-
- - The problem with the DCL idiom in Java is that it just does not work correctly. - Using it introduces bugs that are extremely hard to track down and reproduce. - The - "Double-Checked Locking is Broken" Declaration has an in depth explanation - of the exact problem which has to do with the semantics of the Java memory model. - -- The DoubleCheckedLocking check will find source code where a test is wrapped in a - synchronized block that is wrapped in the same test, like in the example above. - -Examples-- To configure the check: - --<module name="DoubleCheckedLocking"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -EmptyStatementDescription-- Detects empty statements (standalone ;). - -Examples-- To configure the check: - --<module name="EmptyStatement"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -EqualsHashCode-Description-- Checks that classes that override equals() also - override hashCode(). - -- Rationale: The contract of equals() and - hashCode() requires that equal objects have the same hashCode. Hence, - whenever you override equals() you must override - hashCode() to ensure that your class can be used in collections that are - hash based. - - -Example-- To configure the check: - --<module name="EqualsHashCode"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -FinalLocalVariableDescription-- Checks that local variables that never have their values changed - are declared final. The check can be configured to also check that - unchanged parameters are declared final. - -Notes-- When configured to check parameters, the check ignores parameters of interface methods and - abstract methods. - -Properties-
Examples-- To configure the check: - --<module name="FinalLocalVariable"/> -- - To configure the check so that it checks local variables and parameters: - --<module name="FinalLocalVariable"> - <property name="tokens" value="VARIABLE_DEF"/> - <property name="tokens" value="PARAMETER_DEF"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -HiddenFieldDescription-- Checks that a local variable or a parameter does not shadow a field that is - defined in the same class. - -Properties-
Examples-- To configure the check: - --<module name="HiddenField"/> -- - To configure the check so that it checks local variables but not parameters: - --<module name="HiddenField"> - <property name="tokens" value="VARIABLE_DEF"/> -</module> -- - To configure the check so that it ignores the name "rcsid": - --<module name="HiddenField"> - <property name="ignoreFormat" value="^rcsid$"/> -</module> -- - To configure the check so that it ignores constructor parameters: - --<module name="HiddenField"> - <property name="ignoreConstructorParameter" value="true"/> -</module> -- - To configure the check so that it ignores the parameter of setter methods: - --<module name="HiddenField"> - <property name="ignoreSetter" value="true"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -IllegalInstantiationDescription-- Checks for illegal instantiations where a factory method is preferred. - -- Rationale: Depending on the project, for some classes it might be preferable to - create instances through factory methods rather than calling the constructor. - -- A simple example is the java.lang.Boolean class. In - order to save memory and CPU cycles, it is preferable to use the predefined - constants - TRUE and FALSE. Constructor invocations should - be replaced by calls to Boolean.valueOf(). - -- Some extremely performance sensitive projects may require the use of factory - methods for other classes as well, to enforce the usage of number caches or - object pools. - -Notes-- There is a limitation that it is currently not possible to specify array classes. - -Properties-
Example-- To configure the check to find instantiations of java.lang.Boolean: - --<module name="IllegalInstantiation"> - <property name="classes" value="java.lang.Boolean"/> -</module> -- - Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -IllegalTokenDescription-- Checks for illegal tokens. - -- Rational: Certain language features often lead to hard to - maintain code or are non-obvious to novice developers. Other - features may be discouraged in certain frameworks, such as not - having native methods in EJB components. - -Properties-
Example-- To configure the check to find token LITERAL_NATIVE: - --<module name="IllegalToken"> - <property name="tokens" value="LITERAL_NATIVE"/> -</module> -- - Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - - -IllegalTokenTextDescription-- Checks for illegal token text. - -Properties-
Examples-- To configure the check to forbid String literals containing "a href": - --<module name="IllegalTokenText"> - <property name="tokens" value="STRING_LITERAL"/> - <property name="format" value="a href"/> -</module> -- - - To configure the check to forbid leading zeros in an integer literal, other than - zero and a hex literal: - --<module name="IllegalTokenText"> - <property name="tokens" value="NUM_INT,NUM_LONG"/> - <property name="format" value="^0[^lx]"/> - <property name="ignoreCase" value="true"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -InnerAssignmentDescription-- Checks for assignments in subexpressions, such as in String s - = Integer.toString(i = 2);. - -- Rationale: With the exception of for iterators, all - assignments should occur in their own toplevel statement to increase readability. - With inner assignments like the above it is difficult to see all places where a - variable is set. - -Properties-
Examples-- To configure the check: - --<module name="InnerAssignment"/> -- - To configure the check for only =, - +=, and -= operators: - --<module name="InnerAssignment"> - <property name="tokens" value="ASSIGN,PLUS_ASSIGN,MINUS_ASSIGN"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -MagicNumberDescription-- Checks that there are no "magic numbers", where a - magic number is a numeric literal that is not defined as a - constant. By default, -1, 0, 1, and 2 are not considered to - be magic numbers. - -Properties-
Examples-- To configure the check: - --<module name="MagicNumber"/> -- - To configure the check so that it checks floating-point - numbers that are neither 0, 0.5, nor 1: - --<module name="MagicNumber"> - <property name="tokens" value="NUM_DOUBLE, NUM_FLOAT"/> - <property name="ignoreNumbers" value="0, 0.5, 1"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -MissingSwitchDefaultDescription-- Checks that switch statement has "default" clause. - -- Rationale: It's usually a good idea to introduce a default case - in every switch statement. Even if the developer is sure that - all currently possible cases are covered, this should be - expressed in the default branch, e.g. by using an - assertion. This way the code is protected aginst later changes, - e.g. introduction of new types in an enumeration type. - -Examples-- To configure the check: - --<module name="MissingSwitchDefault"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -ModifiedControlVariable-Description-- Check for ensuring that for loop control variables are not modified inside the for - block. An example is: - -
-for (int i = 0; i < 1; i++) {
- i++;
-}
-
- - Rationale: If the control variable is modified inside the loop body, the program - flow becomes more difficult to follow. An option is to replace the for loop - with a while loop. - -Example-- To configure the check: - --<module name="ModifiedControlVariable"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - - -RedundantThrowsDescription-- Checks for redundant exceptions declared in throws clause - such as duplicates, unchecked exceptions or subclasses of - another declared exception. - -Properties-
Examples-- To configure the default check: - --<module name="RedundantThrows"/> -- - To configure the check to allow unchecked exception in throws clause - --<module name="RedundantThrows"> - <property name="allowUnchecked" value="true"/> -</module> -- Note- -The classpath should be configured to locate the class - information. The classpath configuration is dependent on the - mechanism used to invoke Checkstyle. - -Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -SimplifyBooleanExpression-Description-- Checks for overly complicated boolean expressions. Currently finds code like - if (b == true), b || true, !false, etc. - -- Rationale: Complex boolean logic makes code hard to understand and maintain. - -Example-- To configure the check: - --<module name="SimplifyBooleanExpression"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -SimplifyBooleanReturnDescription-- Checks for overly complicated boolean return statements. For example the following code - --if (valid()) - return false; -else - return true; -- - could be written as - --return !valid(); -- - The Idea for this Check has been shamelessly stolen - from the equivalent PMD rule. - -Example-- To configure the check: - --<module name="SimplifyBooleanReturn"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -StringLiteralEquality-Description-
- Checks that string literals are not used with
-
- Rationale: Novice Java programmers often use code like
- Example-- To configure the check: - --<module name="StringLiteralEquality"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -NestedIfDepth-Description-- Restricts nested if-else blocks to a specified depth (default = 1). - - -Properties-
Example-- To configure the check: - --<module name="NestedIfDepth"/> -- - To configure the check to allow nesting depth 3: - --<module name="NestedIfDepth"> - <property name="max" value="3"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -NestedTryDepth-Description-- Restricts nested try blocks to a specified depth (default = 1). - - -Properties-
Example-- To configure the check: - --<module name="NestedTryDepth"/> -- - To configure the check to allow nesting depth 3: - --<module name="NestedTryDepth"> - <property name="max" value="3"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - - -SuperCloneDescription-- Checks that an overriding clone() method invokes super.clone(). - -- Reference: Object.clone(). - -Examples-- To configure the check: - --<module name="SuperClone"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - - -SuperFinalizeDescription-- Checks that an overriding finalize() method invokes super.finalize(). - -- Reference: Cleaning - Up Unused Objects. - -Examples-- To configure the check: - --<module name="SuperFinalize"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -IllegalCatchDescription-- Catching java.lang.Exception, java.lang.Error or java.lang.RuntimeException - is almost never acceptable. - -- Rationale: Junior developers often simply catch Exception in an - attempt to handle multiple exception classes. This unfortunately - leads to code that inadvertantly catchs NPE, OutOfMemoryErrors, - etc. - -Properties-
Examples-- To configure the check: - --<module name="IllegalCatch"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -PackageDeclaration-Description-- Ensure a class is has a package declaration. - -- Rationale: Classes that live in the null package cannot be - imported. Many novice developers are not aware of this. - - -Examples-- To configure the check: - --<module name="PackageDeclaration"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -JUnitTestCase-Description-
- Ensures that the setUp(), tearDown()methods are named correctly,
- have no arguments, return void and are either public or protected. - Rationale: often times developers will misname one or more of these - methods and not realise that the method is not being called. - - -Examples-- To configure the check: - --<module name="JUnitTestCase"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -ReturnCountDescription-- Restricts the number of return statements. Default = 2. - Ignores specified methods (equals() by default). - - -- Rationale: - Too many return points can be indication that code is - attempting to do too much or may be difficult to understand. - - -Properties-
Examples-- To configure the check so that it doesn't allow more than three - return statements per method (equals() - method ignored): - --<module name="ReturnCount"> - <property name="max" value="3"/> -</module> -- - To configure the check so that it doesn't allow more than three - return statements per method for all methods: - --<module name="ReturnCount"> - <property name="max" value="3"/> - <property name="format" value="^$"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -IllegalTypeDescription-- Checks that particular class are never used as types in variable - declarations, return values or parameters. Includes - a pattern check that by default disallows abstract classes. - - -- Rationale: - Helps reduce coupling on concrete classes. In addition abstract - classes should be thought of a convenience base class implementations - of interfaces and as such are not types themsleves. - - -Properties-
Examples-- To configure the check so that it ignore getInstance() method: - --<module name="IllegalType"> - <property name="ignoredMethodNames" value="getInstance"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -DeclarationOrderDescription-- According to - - Code Conventions for the Java Programming Language - , the parts of a class or interface declaration should appear in the - following order - - Examples-- To configure the check: - --<module name="DeclarationOrder"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -ParameterAssignmentDescription-Disallow assignment of parameters. -Rationale: Parameter assignment is often - considered poor programming practice. Forcing developers to - declare parameters as final is often onerous. Having a check - ensure that parameters are never assigned would give the best of - both worlds. - -Examples-- To configure the check: - --<module name="ParameterAssignment"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -ExplicitInitializationDescription-Checks if any class or object member explicitly - initialized to default for its type value (null for object references, zero for numeric - types and char and false for boolean. -Rationale: each instance variable gets - initialized twice, to the same value. Java - initializes each instance variable to its default - value (0 or null) before performing any - initialization specified in the code. So in this case, - x gets initialized to 0 twice, and bar gets initialized - to null twice. So there is a minor inefficiency. This style of - coding is a hold-over from C/C++ style coding, - and it shows that the developer isn't really confident that - Java really initializes instance variables to default - values. - -Examples-- To configure the check: - --<module name="ExplicitInitialization"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -DefaultComesLastDescription-- Check that the default is after all the - cases in a switch - statement. - -- Rationale: Java allows default anywhere - within the switch statement. But it is more - readable if it comes after the last case. - -Examples-- To configure the check: - --<module name="DefaultComesLast"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -MissingCtorDescription-- Checks that classes (except abtract one) define a ctor and don't - rely on the default one. - -Examples-- To configure the check: - --<module name="MissingCtor"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -FallThroughDescription-
- Checks for fall through in switch statements
- Finds locations where a case contains - Note: the check works in assumption that there is no unreachable - code in the case. - -Examples-- To configure the check: - --<module name="FallThrough"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - - -MultipleStringLiteralsDescription-- Checks for multiple occurrences of the same string literal within a - single file. - -- Rationale: Code duplication makes maintenance more difficult, so it - can be better to replace the multiple occurrences with a constant. - -Properties-
Examples-- To configure the check: - --<module name="MultipleStringLiterals"/> -- - To configure the check so that it allows two occurrences of each string: - --<module name="MultipleStringLiterals"> - <property name="allowedDuplicates" value="2"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - - -MultipleVariableDeclarationsDescription-- Checks that each variable declaration is in its own statement - and on its own line. - -- Rationale: - the SUN Code conventions chapter 6.1 recommends that - declarations should be one per line/statement. - -Examples-- To configure the check: - --<module name="MultipleVariableDeclarations"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - -RequireThisDescription-- Checks that code doesn't rely on the "this." default, - i.e. references to instance variables and methods of the present - object are explicitly of the form "this.varName" or - "this.methodName(args)". - -Properties-
Examples-- To configure the default check: - --<module name="RequireThis"/> --
- To configure to check -<module name="RequireThis"> - <property name="checkMethods" value="false"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - - -UnnecessaryParenthesesDescription-- Checks for the use of unnecessary parentheses. - -Examples-- To configure the check: - --<module name="UnnecessaryParentheses"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.coding - -Parent Module-- TreeWalker - - - |
-
-Copyright © 2002-2004 Oliver Burn. All rights Reserved. -
- - - diff --git a/docs/config_design.html b/docs/config_design.html deleted file mode 100644 index 4540fc64d..000000000 --- a/docs/config_design.html +++ /dev/null @@ -1,415 +0,0 @@ - - - - -Class Design Checks |
- |
-
-
|
-
-
- VisibilityModifier-- Checks visibility of class members. Only static final members - may be public; other class members must be private unless - property protectedAllowed or packageAllowed is set. - - -- Public members are not flagged if the name matches the public - member regular expression (contains "^serialVersionUID$" by default). Note: - Checkstyle 2 used to include "^f[A-Z][a-zA-Z0-9]*$" in the default - pattern to allow CMP for EJB 1.1 with the default settings. - With EJB 2.0 it is not longer necessary to have public access - for persistent fields, hence the default has been changed. - -- Rationale: Enforce encapsulation. - - - -Properties-
Examples-- To configure the check: - --<module name="VisibilityModifier"/> -- - To configure the check so that it allows package visible members: - --<module name="VisibilityModifier"> - <property name="packageAllowed" value="true"/> -</module> -- - To configure the check so that it allows no public members: - --<module name="VisibilityModifier"> - <property name="publicMemberPattern" value="^$"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.design - -Parent Module-- TreeWalker - - -FinalClass- -- Checks that a class which has only private constructors is declared as final. - -Example-- To configure the check: - --<module name="FinalClass"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.design - -Parent Module-- TreeWalker - -InterfaceIsTypeDescription-- Implements Bloch, Effective Java, Item 17 - - Use Interfaces only to define types. - - -- According to Bloch, an interface should describe a type. - It is therefore inappropriate to define an interface that does not - contain any methods but only constants. The Standard class - javax.swing.SwingConstants - is an example of a class that would be flagged by this check. - - -
- The check can be configured to also disallow marker interfaces like
- Properties-
Examples-- To configure the check: - --<module name="InterfaceIsType"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.design - -Parent Module-- TreeWalker - - -HideUtilityClassConstructorDescription-- Make sure that utility classes (classes that contain only static methods) - do not have a public constructor. - -- Rationale: Instantiating utility classes does not make sense. - Hence the constructors should either be private or (if you - want to allow subclassing) protected. A common mistake is forgetting - to hide the default constructor. - -- If you make the constructor protected you may want to consider - the following constructor implementation technique to disallow - instantiating subclasses: - -
-public class StringUtils // not final to allow subclassing
-{
- protected StringUtils() {
- throw new UnsupportedOperationException(); // prevents calls from subclass
- }
-
- public static int count(char c, String s) {
- // ...
- }
-}
-
- Examples-- To configure the check: - --<module name="HideUtilityClassConstructor"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.design - -Parent Module-- TreeWalker - - -DesignForExtensionDescription-- Checks that classes are designed for extension. - More specifically, it enforces a programming style - where superclasses provide empty "hooks" that can be - implemented by subclasses. - - -- The exact rule is that nonprivate, nonstatic methods of classes that - can be subclassed must either be - -
- Rationale: This API design style protects superclasses against beeing broken by - subclasses. The downside is that subclasses are limited in their flexibility, - in particular they cannot prevent execution of code in the superclass, but that also - means that subclasses cannot corrupt the state of the superclass by forgetting to - call the super method. - - -Properties- None. - -Examples-- To configure the check: - --<module name="DesignForExtension"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.design - -Parent Module-- TreeWalker - - -MutableExceptionDescription-- Ensures that exceptions (defined as any class name conforming - to some regular expression) are immutable. That is, have only - final fields. - - -- The current algorithm is very simple it checks that all - members of exception are final. User can still mutates an - exception's instance (e.g. Throwable has - setStackTrace(StackTraceElement[] stackTrace) method which - changes stack trace). But, at least, all information provided - by this exception type is unchangable. - - -- Rationale: - Exception instances should represent an error - condition. Having non final fields not only allows the - state to be modified by accident and therefore mask the - original condition but also allows developers to - accidentally forget to initialise state thereby leading - to code catching the exception to draw incorrect - conclusions based on the state. - - -Properties-
Examples-- To configure the check: - --<module name="MutableException"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.design - -Parent Module-- TreeWalker - - -ThrowsCountDescription-- Restricts throws statements to a specified count (default = 1). - - -- Rationale: - Exceptions form part of a methods interface. Declaring - a method to throw too many differently rooted - exceptions makes exception handling onerous and leads - to poor programming practices such as catch - (Exception). This check forces developers to put - exceptions into a heirachy such that in the simplest - case, only one type of exception need be checked for by - a caller but allows any sub-classes to be caught - specifically if necessary. - - -Properties-
Examples-- To configure the check so that it doesn't allow more than two - throws per method: - --<module name="ThrowsCount"> - <property name="max" value="2"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.design - -Parent Module-- TreeWalker - - - |
-
-Copyright © 2002-2004 Oliver Burn. All rights Reserved. -
- - - diff --git a/docs/config_import.html b/docs/config_import.html deleted file mode 100644 index e2b37b67c..000000000 --- a/docs/config_import.html +++ /dev/null @@ -1,295 +0,0 @@ - - - - -Checks for imports |
- |
-
-
|
-
-
- AvoidStarImport-Description-- Checks that there are no import statements that use the * notation. - -- Rationale: Importing all classes from a package leads to tight coupling - between packages and might lead to problems when a new version of a library - introduces name clashes. - -Properties-
Example-- An example how to configure the check so that star imports - from java.io and java.net are allowed: - --<module name="AvoidStarImport"> - <property name="excludes" value="java.io,java.net"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.imports - -Parent Module-- TreeWalker - -IllegalImport-Description- -- Checks for imports from a set of illegal packages. By default, the check rejects - all sun.* packages since programs that contain direct - calls to the sun.* packages are not - 100% Pure Java. To reject other packages, set property - illegalPkgs to a list of the illegal packages. - -Properties-
Examples-- To configure the check: - --<module name="IllegalImport"/> -- - To configure the check so that it rejects packages java.io.* - and java.sql.*: - --<module name="IllegalImport"> - <property name="illegalPkgs" value="java.io, java.sql"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.imports - -Parent Module-- TreeWalker - -RedundantImportDescription-- Checks for redundant import statements. An import statement is considered - redundant if: - -
Example-- To configure the check: - --<module name="RedundantImport"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.imports - - -Parent Module-- TreeWalker - -UnusedImportsDescription-- Checks for unused import statements. Checkstyle uses a simple but very reliable - algorithm to report on unused import statements. An import statement is - considered unused if: - - -
Example-- To configure the check: - --<module name="UnusedImports"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.imports - - -Parent Module-- TreeWalker - - -ImportOrderDescription-Checks the ordering/grouping of imports. - Ensures that groups of imports come in a specific order (e.g., - java. comes first, javax. comes first, then everything else) and - imports within each group are in lexicographic order. - - -Properties-
Example-- To configure the check so that it requires "java" - packages first, than "javax" and than all other - imports, imports will be sorted in the groups and groups are - separated by, at least, on blank line: - -- <module name="ImportOrder"> - <property name="groups" value="java,javax"/> - <property name="ordered" value="true"/> - <property name="separated" value="true"/> - </module> -- Package-- com.puppycrawl.tools.checkstyle.checks.imports - - -Parent Module-- TreeWalker - - |
-
-Copyright © 2002-2004 Oliver Burn. All rights Reserved. -
- - - diff --git a/docs/config_j2ee.html b/docs/config_j2ee.html deleted file mode 100644 index 51bab748f..000000000 --- a/docs/config_j2ee.html +++ /dev/null @@ -1,511 +0,0 @@ - - - - -Checks for J2EE coding problems |
- |
-
-
|
-
-
-
- EntityBeanDescription-- Checks that a direct entity bean, i.e. a class that directly implements - javax.ejb.EntityBean, satisfies these class requirements: - -
- Checks that methods of a direct entity bean satisfy these requirements: - -
- When the check is configured to check direct entity beans as having bean-managed - persistence, checks that methods satisfy these additional requirements: - -
- When the check is configured to check direct entity beans as having container-managed - persistence, checks that methods satisfy these additional requirements: - -
Properties-
- Reference: Enterprise JavaBeans™ Specification,Version 2.0, sections - 10.6 and 12.2. - -Example-- To configure the check: - --<module name="j2ee.EntityBean"/> -- - To configure the check to apply the container policy to direct entity beans: - --<module name="j2ee.EntityBean"> - <property name="persistence" value="container"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.j2ee - -Parent Module-- TreeWalker - - -FinalStaticDescription-- Checks that all static fields are declared final. - -- Rational: This check ensures consistent runtime semantics so that EJB containers have - the flexibility to distribute instances across multiple JVMs. - -- Reference: Programming restrictions on EJB. - -Example-- To configure the check: - --<module name="j2ee.FinalStatic"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.j2ee - -Parent Module-- TreeWalker - - -LocalHomeInterfaceDescription-- Checks that a direct local home interface, i.e. an interface that directly extends - javax.ejb.EJBLocalHome, satisfies these requirements: - -
- Reference: Enterprise JavaBeansTM Specification,Version 2.0, sections 6.4 and 9.6. - -Example-- To configure the check: - --<module name="j2ee.LocalHomeInterface"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.j2ee - -Parent Module-- TreeWalker - - -LocalInterfaceDescription-- Checks that a direct local interface, i.e. an interface that directly extends - javax.ejb.EJBLocalObject, satisfies these requirements: - -
- Reference: Enterprise JavaBeansTM Specification,Version 2.0, section 9.10. - -Example-- To configure the check: - --<module name="j2ee.LocalInterface"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.j2ee - -Parent Module-- TreeWalker - - -MessageBeanDescription-- Checks that a direct message bean, i.e. a class that directly implements - javax.ejb.MessageDrivenBean and - javax.jms.MessageListener, satisfies these class requirements: - -
- Reference: Enterprise JavaBeans™ Specification,Version 2.0, section 15.7. - -Example-- To configure the check: - --<module name="j2ee.MessageBean"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.j2ee - -Parent Module-- TreeWalker - - -RemoteHomeInterfaceDescription-- Checks that a direct remote home interface, i.e. an interface that directly extends - javax.ejb.EJBHome, satisfies these requirements: - -
- Reference: Enterprise JavaBeansTM Specification,Version 2.0, sections 6.3 and 9.5. - -Example-- To configure the check: - --<module name="j2ee.RemoteHomeInterface"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.j2ee - -Parent Module-- TreeWalker - - -RemoteInterfaceDescription-- Checks that a direct remote interface, i.e. an interface that directly extends - javax.ejb.EJBObject, satisfies these requirements: - -
- Reference: Enterprise JavaBeansTM Specification,Version 2.0, section 9.9. - -Example-- To configure the check: - --<module name="j2ee.RemoteInterface"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.j2ee - -Parent Module-- TreeWalker - - -SessionBeanDescription-- Checks that a direct session bean, i.e. a class that directly implements - javax.ejb.SessionBean, satisfies these class requirements: - -
- Reference: Enterprise JavaBeans™ Specification,Version 2.0, section 7.10. - -Example-- To configure the check: - --<module name="j2ee.SessionBean"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.j2ee - -Parent Module-- TreeWalker - - - -ThisParameterDescription-- Checks that this is not a parameter of any method calls or constructors for a bean. - Instead, you must use the result of the getEJBObject() available in - SessionContext or EntityContext. - -- Reference: Programming restrictions on EJB. - -Example-- To configure the check: - --<module name="j2ee.ThisParameter"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.j2ee - -Parent Module-- TreeWalker - - - -ThisReturnDescription-- Checks that this is not returned by a bean method. - Instead, you must use the result of the getEJBObject() available in - SessionContext or EntityContext. - -- Reference: Programming restrictions on EJB. - -Example-- To configure the check: - --<module name="j2ee.ThisReturn"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.j2ee - -Parent Module-- TreeWalker - - - |
-
-Copyright © 2002-2004 Oliver Burn. All rights Reserved. -
- - - diff --git a/docs/config_javadoc.html b/docs/config_javadoc.html deleted file mode 100644 index 5889d5940..000000000 --- a/docs/config_javadoc.html +++ /dev/null @@ -1,597 +0,0 @@ - - - - -Checks for Javadoc Comments |
- |
-
-
|
-
-
-
- PackageHtmlDescription-- Checks that a package.html file exists for each - package. More specifically, checks that each java file has a package.html sibling. - - -Properties-
Example-- To configure the check: - --<module name="PackageHtml"/> -- - Package-- com.puppycrawl.tools.checkstyle.checks.javadoc - -Parent Module-- Checker - - -JavadocTypeDescription-- Checks Javadoc comments for class and interface definitions. - - -Properties- -
Examples-- To configure the default check: - --<module name="JavadocType"/> -- - To configure the check for public scope: - --<module name="JavadocType"> - <property name="scope" value="public"/> -</module> -- - To configure the check for an @author tag: - --<module name="JavadocType"> - <property name="authorFormat" value="\S"/> -</module> -- - To configure the check for a CVS revision version tag: - --<module name="JavadocType"> - <property name="versionFormat" value="\$Revision.*\$"/> -</module> -- - To configure the check for private classes only: - --<module name="JavadocType"> - <property name="scope" value="private"/> - <property name="excludescope" value="package"/> -</module> -- - Package-- com.puppycrawl.tools.checkstyle.checks.javadoc - -Parent Module-- TreeWalker - - -JavadocMethodDescription-- Checks to ensure that the following tags exist (if required): - -
- For example, the following is valid: - - -- /** - * Checks for a return tag. - * @return the index of the next unchecked tag - * @param aTagIndex the index to start in the tags - * @param aTags the tags to check - * @param aLineNo the line number of the expected tag - **/ - public int checkReturnTag(final int aTagIndex, - JavadocTag[] aTags, - int aLineNo) -- - - This supports the convention in the Sun - Javadoc Guidelines and the "Effective Java" book. - - -Properties- -
Examples-- To configure the default check: - --<module name="JavadocMethod"/> -- - To configure the check for public - scope and to allow documentation of undeclared RuntimeExceptions: - --<module name="JavadocMethod"> - <property name="scope" value="public"/> - <property name="allowUndeclaredRTE" value="true"/> -</module> -- - To configure the check for methods which are in private , but not in protected scope: - --<module name="JavadocMethod"> - <property name="scope" value="private"/> - <property name="excludeScope" value="protected"/> -</module> -- Notes- -
Package-- com.puppycrawl.tools.checkstyle.checks.javadoc - -Parent Module-- TreeWalker - - - -JavadocVariableDescription-- Checks that variables have Javadoc comments. - -Properties- -
Examples-- To configure the default check: - --<module name="JavadocVariable"/> -- - To configure the check for public scope: - --<module name="JavadocVariable"> - <property name="scope" value="public"/> -</module> -- - To configure the check for members which are in private, but not in protected scope: - --<module name="JavadocVariable"> - <property name="scope" value="private"/> - <property name="excludeScope" value="protected"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.javadoc - -Parent Module-- TreeWalker - - - - -JavadocStyle-Description- -- Validates Javadoc comments to help ensure they are well formed. - The following checks are performed: - - -
These checks were patterned after the checks made by the DocCheck - doclet available from Sun. - -Properties- -
Examples- -- To configure the default check: - - --<module name="JavadocStyle"/> -- - - To configure the check for public scope: - - --<module name="JavadocStyle"> - <property name="scope" value="public"/> -</module> -- - To configure the check for javadoc which is in private, but not in package scope: - - --<module name="JavadocStyle"> - <property name="scope" value="private"/> - <property name="excludeScope" value="package"/> -</module> -- - To configure the check to turn off first sentence checking: - --<module name="JavadocStyle"> - <property name="checkFirstSentence" value="false"/> -</module> -- - - - Package-- com.puppycrawl.tools.checkstyle.checks - -Parent Module-- TreeWalker - - |
-
- Copyright © 2002-2004 Oliver Burn. All rights Reserved. -
- - - diff --git a/docs/config_metrics.html b/docs/config_metrics.html deleted file mode 100644 index 7004da666..000000000 --- a/docs/config_metrics.html +++ /dev/null @@ -1,436 +0,0 @@ - - - - -Metrics Checks |
- |
-
| - - | - -
-
-
- BooleanExpressionComplexity-Description- -- Restrict the number of number of &&, - || and ^ in - an expression. - -- Rationale: - Too many conditions leads to code that is difficult to - read and hence debug and maintain. - - - -Properties-
Examples-- To configure the check: - --<module name="BooleanExpressionComplexity"/> -- - To configure the check with 7 allowed operation in boolean expression: - --<module name="BooleanExpressionComplexity"> - <property name="max" value="7"/> -</module> - -- - Package-- com.puppycrawl.tools.checkstyle.checks.metrics - - -Parent Module-- TreeWalker - - -ClassDataAbstractionCoupling-Description- -- This metric measures the number of instantiations of - other classes within the given class. This type of - coupling is not caused by inheritance or the object - oriented paradigm. Generally speaking, any abstract - data type with other abstract data types as members has - data abstraction coupling; therefore, if a class has a - local variable that is an instantiation (object) of - another class, there is data abstraction coupling. The - higher the DAC, the more complex the data structure - (classes) of the system. - - - -Properties-
Examples-- To configure the check: - --<module name="ClassDataAbstractionCoupling"/> -- - To configure the check with a threshold of 5: - --<module name="ClassDataAbstractionCoupling"> - <property name="max" value="5"/> -</module> - -- - Package-- com.puppycrawl.tools.checkstyle.checks.metrics - - -Parent Module-- TreeWalker - - -ClassFanOutComplexity-Description- -- The number of other classes a given class relies on. Also - the square of this has been shown to indicate the - amount of maintenence required in functional programs - (on a file basis) at least. - - - -Properties-
Examples-- To configure the check: - --<module name="ClassFanOutComplexity"/> -- - To configure the check with a threshold of 10: - --<module name="ClassFanOutComplexity"> - <property name="max" value="10"/> -</module> - -- - Package-- com.puppycrawl.tools.checkstyle.checks.metrics - - -Parent Module-- TreeWalker - - -CyclomaticComplexity-Description- --Checks cyclomatic complexity against a specified limit. The complexity is -measured by the number of - if, - while, - do, - for, - ?:, - catch, - switch, - case statements, and operators - && and || (plus one) in the body of a -constructor, method, static initializer, or instance initializer. - It is a measure of the minimum number of possible paths through the -source and therefore the number of required tests. Generally 1-4 is -considered good, 5-7 ok, 8-10 consider re-factoring, and 11+ re-factor now! - - - -Properties-
Examples-- To configure the check: - --<module name="CyclomaticComplexity"/> -- - To configure the check with a threshold of 7: - --<module name="CyclomaticComplexity"> - <property name="max" value="7"/> -</module> - -- - Package-- com.puppycrawl.tools.checkstyle.checks.metrics - - -Parent Module-- TreeWalker - - -NPathComplexity-Description- -- The NPATH metric computes the number of possible - execution paths through a function. It takes into - account the nesting of conditional statements and - multi-part boolean expressions (e.g., A && B, C || D, - etc.). - -- Rationale: - Nejmeh says that his group had an informal NPATH limit - of 200 on individual routines; functions that exceeded - this value were candidates for further decomposition - - or at least a closer look. - - - -Properties-
Examples-- To configure the check: - --<module name="NPathComplexity"/> -- - To configure the check with a threshold of 20: - --<module name="NPathComplexity"> - <property name="max" value="20"/> -</module> - -- - Package-- com.puppycrawl.tools.checkstyle.checks.metrics - - -Parent Module-- TreeWalker - - - -JavaNCSS-Description- -
- Determines complexity of methods, classes and files by counting
- the Non Commenting Source Statements (NCSS).
- This check adheres to the
- specification for the JavaNCSS-Tool written by
- Chr. Clemens Lee which sadly seems to have been pulled
- off the web. - Rationale: - Too large methods and classes are hard to read and costly to - maintain. A large NCSS number often means that a method or - class has too many responsabilities and/or functionalities - which should be decomposed into smaller units. - - - -Properties-
Examples-- To configure the check: - --<module name="JavaNCSS"/> -- - To configure the check with 40 allowed non commenting lines - for a method: - --<module name="JavaNCSS"> - <property name="methodMaximum" value="40"/> -</module> - -- - Package-- com.puppycrawl.tools.checkstyle.checks.metrics - - -Parent Module-- TreeWalker - - - |
-
-Copyright © 2002-2004 Oliver Burn. All rights Reserved. -
- - - diff --git a/docs/config_misc.html b/docs/config_misc.html deleted file mode 100644 index b36ac5473..000000000 --- a/docs/config_misc.html +++ /dev/null @@ -1,930 +0,0 @@ - - - - -Miscellaneous Checks |
- |
-
-
|
-
-
-
- GenericIllegalRegexpDescription-- A generic check for code problems - the user can search for any pattern. This is - similar to a recursive grep, only that it's integrated in checkstyle. - -- Rationale: This check can be used to prototype checks and to find common bad - practice such as calling ex.printStacktrace(), - System.out.println(), System.exit(), etc. - -Properties-
Examples-- To configure the check for calls to System.out.println: - --<module name="GenericIllegalRegexp"> - <!-- . matches any character, so we need to - escape it and use \. to match dots. --> - <property name="format" value="System\.out\.println"/> -</module> -- - To configure the check to find trailing whitespace at the end of a line: - --<module name="GenericIllegalRegexp"> - <!-- \s matches whitespace character, $ matches end of line. --> - <property name="format" value="\s$"/> -</module> -- - To configure the check to find case-insensitive occurrences of "debug": - --<module name="GenericIllegalRegexp"> - <property name="format" value="debug"/> - <property name="ignoreCase" value="true"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks - -Parent Module-- TreeWalker - -NewlineAtEndOfFileDescription-- Checks whether files end with a new line. - -- Rationale: Any source files and text files in general should end with a newline - character, especially when using SCM systems such as CVS. CVS will even - print a warning when it encounters a file that doesn't end with a newline. - -Properties-
Examples-- To configure the check: - --<module name="NewlineAtEndOfFile"/> -- - To configure the check to always use Unix-style line separators: - --<module name="NewlineAtEndOfFile"> - <property name="lineSeparator" value="lf"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks - -Parent Module-- Checker - -TodoCommentDescription-- A check for TODO: comments. Actually it is a generic regular - expression matcher on Java comments. To check for other patterns in Java - comments, set property format. - -Properties-
Notes-- Using TODO: comments is a great way to keep track of - tasks that need to be done. Having them reported by Checkstyle makes it very - hard to forget about them. - -Examples-- To configure the check: - --<module name="TodoComment"/> -- - To configure the check for comments that contain WARNING: - --<module name="TodoComment"> - <property name="format" value="WARNING"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks - -Parent Module-- TreeWalker - -TranslationDescription-- A FileSetCheck that ensures the correct - translation of code by checking property files for consistency regarding their - keys. Two property files describing one and the same context are consistent if - they contain the same keys. - -- Consider the following properties file in the same directory: - -- #messages.properties - hello=Hello - cancel=Cancel - - #messages_de.properties - hell=Hallo - ok=OK -- - The Translation check will find the typo in the german hello key, the - missing ok key in the default resource file and the missing cancel key - in the german resource file: - -- messages_de.properties: Key 'hello' missing. - messages_de.properties: Key 'cancel' missing. - messages.properties: Key 'hell' missing. - messages.properties: Key 'ok' missing. -- Properties-
Example-- To configure the check: - --<module name="Translation"/> -- Package-- com.puppycrawl.tools.checkstyle.checks - -Parent Module-- Checker - -UncommentedMainDescription-- Checks for uncommented main() methods (debugging leftovers). - -Rationale: A main() method is often used for - debug puposes. When debugging is finished, developers often forget - to remove the method, which changes the API and increases the size - of the resulting class/jar file. With the exception of the real - program entry points, all main() methods should be removed/commented - out of the sources. - -Properties-
Examples-- To configure the check: - --<module name="UncommentedMain"/> -- - To configure the check to allow main method for all classes with - "Main" name: - --<module name="UncommentedMain"> - <property name="excludedClasses" value="\.Main$"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks - - -Parent Module-- TreeWalker - - - -UpperEllDescription-- Checks that long constants are defined with an upper ell. That is ' - L' and -not 'l'. This is in accordance to the Java Language -Specification, -Section - 3.10.1. - -Rationale: The letter l looks a lot -like 1. - -Examples-- To configure the check: - - --<module name="UpperEll"/> -- Package-- com.puppycrawl.tools.checkstyle.checks - - -Parent Module-- TreeWalker - - - -ArrayTypeStyleDescription-
- Checks the style of array type definitions.
- Some like Java-style: Properties-
Examples-- To configure the check to enforce Java style: - --<module name="ArrayTypeStyle"/> -- - To configure the check to enforce C style: - --<module name="ArrayTypeStyle"> - <property name="javaStyle" value="false"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks - -Parent Module-- TreeWalker - - -FinalParametersDescription-- Check that method/constructor/catch block parameters are final. Interface and abstract methods are not checked - - the final keyword does not make sense for interface and abstract method parameters as there is no code - that could modify the parameter. - -- Rationale: Changing the value of parameters during the execution of the - method's algorithm can be confusing and should be avoided. A great way to - let the Java compiler prevent this coding style is to declare parameters - final. - - -Properties-
Examples-- To configure the check to enforce final parameters for methods and constructors: - --<module name="FinalParameters"/> -- - To configure the check to enforce final parameters only for constructors: - --<module name="FinalParameters"> - <property name="tokens" value="CTOR_DEF"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks - -Parent Module-- TreeWalker - - -DescendantTokenDescription-- Checks for restricted tokens beneath other tokens. - -- WARNING: This is a very powerful and flexible check, but, at the - same time, it is low level and very implementation dependent - because its results depend on the grammar we use to build abstract - syntax trees. Thus we recomend using other checks when - they provide the desired funcionality. All in all, this check just - works on the level of an abstract tree and knows nothing about language - structures. - - -Properties-
Examples-- String literal equality check: - <module name="DescendantToken"> - <property name="tokens" value="EQUAL,NOT_EQUAL"/> - <property name="limitedTokens" value="STRING_LITERAL"/> - <property name="maximumNumber" value="0"/> - <property name="maximumDepth" value="1"/> - </module> - - Switch with no default: - <module name="DescendantToken"> - <property name="tokens" value="LITERAL_SWITCH"/> - <property name="maximumDepth" value="2"/> - <property name="limitedTokens" value="LITERAL_DEFAULT"/> - <property name="minimumNumber" value="1"/> - </module> - - Assert statement may have side effects (formatted for browser display): - <module name="DescendantToken"> - <property name="tokens" value="LITERAL_ASSERT"/> - <property name="limitedTokens" value="ASSIGN,DEC,INC,POST_DEC, - POST_INC,PLUS_ASSIGN,MINUS_ASSIGN,STAR_ASSIGN,DIV_ASSIGN,MOD_ASSIGN, - BSR_ASSIGN,SR_ASSIGN,SL_ASSIGN,BAND_ASSIGN,BXOR_ASSIGN,BOR_ASSIGN, - METHOD_CALL"/> - <property name="maximumNumber" value="0"/> - </module> - - Initialiser in for performs no setup (use while instead?): - <module name="DescendantToken"> - <property name="tokens" value="FOR_INIT"/> - <property name="limitedTokens" value="EXPR"/> - <property name="minimumNumber" value="1"/> - </module> - - Condition in for performs no check: - <module name="DescendantToken"> - <property name="tokens" value="FOR_CONDITION"/> - <property name="limitedTokens" value="EXPR"/> - <property name="minimumNumber" value="1"/> - </module> - - Switch within switch: - <module name="DescendantToken"> - <property name="tokens" value="LITERAL_SWITCH"/> - <property name="limitedTokens" value="LITERAL_SWITCH"/> - <property name="maximumNumber" value="0"/> - <property name="minimumDepth" value="1"/> - </module> - - Return from within a catch or finally block: - <module name="DescendantToken"> - <property name="tokens" value="LITERAL_FINALLY,LITERAL_CATCH"/> - <property name="limitedTokens" value="LITERAL_RETURN"/> - <property name="maximumNumber" value="0"/> - </module> - - Try within catch or finally block: - <module name="DescendantToken"> - <property name="tokens" value="LITERAL_CATCH,LITERAL_FINALLY"/> - <property name="limitedTokens" value="LITERAL_TRY"/> - <property name="maximumNumber" value="0"/> - </module> - - Too many cases within a switch: - <module name="DescendantToken"> - <property name="tokens" value="LITERAL_SWITCH"/> - <property name="limitedTokens" value="LITERAL_CASE"/> - <property name="maximumDepth" value="2"/> - <property name="maximumNumber" value="10"/> - </module> - - Too many local variables within a method: - <module name="DescendantToken"> - <property name="tokens" value="METHOD_DEF"/> - <property name="limitedTokens" value="VARIABLE_DEF"/> - <property name="maximumDepth" value="2"/> - <property name="maximumNumber" value="10"/> - </module> - - Too many returns from within a method: - <module name="DescendantToken"> - <property name="tokens" value="METHOD_DEF"/> - <property name="limitedTokens" value="LITERAL_RETURN"/> - <property name="maximumNumber" value="3"/> - </module> - - Too many fields within an interface: - <module name="DescendantToken"> - <property name="tokens" value="INTERFACE_DEF"/> - <property name="limitedTokens" value="VARIABLE_DEF"/> - <property name="maximumDepth" value="2"/> - <property name="maximumNumber" value="0"/> - </module> - - Limit the number of exceptions a method can throw: - <module name="DescendantToken"> - <property name="tokens" value="LITERAL_THROWS"/> - <property name="limitedTokens" value="IDENT"/> - <property name="maximumNumber" value="1"/> - </module> - - Limit the number of expressions in a method: - <module name="DescendantToken"> - <property name="tokens" value="METHOD_DEF"/> - <property name="limitedTokens" value="EXPR"/> - <property name="maximumNumber" value="200"/> - </module> - - Disallow empty statements: - <module name="DescendantToken"> - <property name="tokens" value="EMPTY_STAT"/> - <property name="limitedTokens" value="EMPTY_STAT"/> - <property name="maximumNumber" value="0"/> - <property name="maximumDepth" value="0"/> - <property name="maximumMessage" - value="Empty statement is not allowed."/> - </module> - - Too many fields within a class: - <module name="DescendantToken"> - <property name="tokens" value="CLASS_DEF"/> - <property name="limitedTokens" value="VARIABLE_DEF"/> - <property name="maximumDepth" value="2"/> - <property name="maximumNumber" value="10"/> - </module> -- Package-- com.puppycrawl.tools.checkstyle.checks - -Parent Module-- TreeWalker - - - Indentation -IndentationDescription-- Checks correct indentation of Java Code. - -- The basic idea behind this is that while - pretty printers are sometimes convienent for bulk reformats of - legacy code, they often either aren't configurable enough or - just can't anticipate how format should be done. Sometimes this is - personal preference, other times it is practical experience. In any - case, this check should just ensure that a minimal set of indentation - rules are followed. - - -Properties-
Examples-- To configure the check: - -<module name="Indentation"/> -- - - To configure the check to enforce indentation style recommended - by Sun: - -<module name="Indentation"> - <property name="caseIndent" value="0"/> -</module> -- - Package-- com.puppycrawl.tools.checkstyle.checks.indentation - -Parent Module-- TreeWalker - - - TrailingComment -TrailingCommentDescription-
- The check to ensure that requires that comments be the only thing on a line.
- For the case of // comments that means that the only thing that should
- precede it is whitespace.
- It doesn't check comments if they do not end line, i.e. it accept
- the following:
- - Rationale: Steve McConnel in "Code Complete" suggests that endline - comments are a bad practice. An end line comment would - be one that is on the same line as actual code. For example: - - a = b + c; // Some insightful comment - d = e / f; // Another comment for this line -- Quoting "Code Complete" for the justfication: -
Properties-
Examples-- To configure the check: - -<module name="TrailingComment"/> -- - - To configure the check so it enforces only comment on a line: - -<module name="TrailingComment"> - <property name="format" value="^\\s*$"/> - </module> -- - Package-- com.puppycrawl.tools.checkstyle.checks.indentation - -Parent Module-- TreeWalker - - -RequiredRegexpDescription-- A check that makes sure that a specified pattern exists in the code, e.g. a required - legal text. It does not care about where in the file the pattern is. - -Properties-
Examples-- An example of how to configure the check to make sure a copyright statement - is included in the file: - -- <module name="RequiredRegexp"> - <property name="format" value="This code is copyrighted"/> - </module> -- - Package-- com.puppycrawl.tools.checkstyle.checks - -Parent Module-- TreeWalker - - - |
-
-Copyright © 2002-2004 Oliver Burn. All rights Reserved. -
- - - diff --git a/docs/config_modifiers.html b/docs/config_modifiers.html deleted file mode 100644 index 2d29a6613..000000000 --- a/docs/config_modifiers.html +++ /dev/null @@ -1,184 +0,0 @@ - - - - -Modifier Checks |
- |
-
-
|
-
-
-
- ModifierOrder-Description- -- Checks that the order of modifiers conforms to the suggestions in the Java - Language specification, sections 8.1.1, 8.3.1 and 8.4.3. The correct order - is: - - -
Example-- To configure the check: - --<module name="ModifierOrder"/> -- - Package-- com.puppycrawl.tools.checkstyle.checks - - -Parent Module-- TreeWalker - -RedundantModifier- -- Checks that -
Properties-
Example-- To configure the check: - --<module name="RedundantModifier"/> -- - To configure the check to check only methods and not variables: - --<module name="RedundantModifier"> - <property name="tokens" value="METHOD_DEF"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks - -Parent Module-- TreeWalker - - - - |
-
-Copyright © 2002-2004 Oliver Burn. All rights Reserved. -
- - - diff --git a/docs/config_naming.html b/docs/config_naming.html deleted file mode 100644 index 8897ec265..000000000 --- a/docs/config_naming.html +++ /dev/null @@ -1,192 +0,0 @@ - - - - -Checks for Naming Conventions |
- |
-
- Each of these naming modules validates identifiers for particular code elements. Valid - identifiers for a naming module are specified by its - format property. The value of format is a regular - expression for valid identifiers. - This is an example of a configuration of the MemberName module to - ensure that member identifiers begin with 'm', - followed by an upper case letter, and then letters and digits: -
-- <module name="MemberName"> - <property name="format" value="^m[A-Z][a-zA-Z0-9]*$"/> - </module> --
- All naming modules belong to package - com.puppycrawl.tools.checkstyle.checks.naming and are submodules of - TreeWalker. -
-| module | -validates identifiers for | -default value of format | -
|---|---|---|
| AbstractClassName | -abstract classes | -^Abstract.*$|^.*Factory$ | -
| ConstantName | -constants (static, - final fields) | -^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$ | -
| LocalFinalVariableName | -local, final variables | -^[a-z][a-zA-Z0-9]*$ | -
| LocalVariableName | -local, non-final variables, including - catch parameters | -^[a-z][a-zA-Z0-9]*$ | -
| MemberName | -non-static fields | -^[a-z][a-zA-Z0-9]*$ | -
| MethodName | -methods | -^[a-z][a-zA-Z0-9]*$ | -
| PackageName | -packages | -^[a-z]+(\.[a-zA-Z_][a-zA-Z0-9_]*)*$ | -
| ParameterName | -parameters | -^[a-z][a-zA-Z0-9]*$ | -
| StaticVariableName | -static, non-final fields | -^[a-z][a-zA-Z0-9]*$ | -
| TypeName | -classes and interfaces | -^[A-Z][a-zA-Z0-9]*$ | -
- <module name="PackageName"> - <property name="format" value="^[a-z]+(\.[a-z][a-z0-9]*)*$"/> - </module> --
- <module name="LocalVariableName"> - <property name="format" value="^e[a-zA-Z0-9]*$"/> - <property name="tokens" value="PARAMETER_DEF"/> - </module> --
- <module name="TypeName"> - <property name="format" value="^I_[a-zA-Z0-9]*$"/> - <property name="tokens" value="INTERFACE_DEF"/> - </module> --
| name | -description | -type | -default value | -
|---|---|---|---|
| applyToPublic | -Controls whether to apply the check to public member. | -Boolean | -true | -
| applyToProtected | -Controls whether to apply the check to protected member. | -Boolean | -true | -
| applyToPackage | -Controls whether to apply the check to package-private member. | -Boolean | -true | -
| applyToPrivate | -Controls whether to apply the check to pribvate member. | -Boolean | -true | -
-Copyright © 2002-2004 Oliver Burn. All rights Reserved. -
- - - \ No newline at end of file diff --git a/docs/config_reporting.html b/docs/config_reporting.html deleted file mode 100644 index 19271fe27..000000000 --- a/docs/config_reporting.html +++ /dev/null @@ -1,57 +0,0 @@ - - - - -The property checkstyle.cache.file specifies the -name of a file that can be used to cache details of files that pass -Checkstyle. This can significantly increase the speed of checkstyle on -successive runs. The property type is -string and defaults to an empty string -(which means do not cache).
- - -Checkstyle supports a mechanism for localising the output messages. If your -language is not supported, please consider translating the messages in the -messages.properties file. Please let us know if -you translate the file.
- -The property checkstyle.locale.language specifies -the language to use in localising the output messages. The property type is -string and defaults to the default -system locale language.
- -The property checkstyle.locale.country specifies -the country to use in localising the output messages. The property type is -string and defaults to the default -system locale country.
- - -The property checkstyle.basedir specifies a base -directory which files are then reported relative to. For example, if a base -directory is specified as c:\projects\checkstyle, -then an error in the file c:\projects\checkstyle\src\dir\subdir\File.java will be -reported as src\dir\subdir\File.java. The property -type is string and defaults to an -empty string.
- -Copyright © 2002-2004 Oliver Burn. All rights Reserved.
- - - diff --git a/docs/config_sizes.html b/docs/config_sizes.html deleted file mode 100644 index ab3dd367e..000000000 --- a/docs/config_sizes.html +++ /dev/null @@ -1,455 +0,0 @@ - - - - -Checks for Size Violations |
- |
-
-
|
-
-
-
-
-
- ExecutableStatementCount-Description- -- Restricts the number of executable statements to a specified limit. - - - -Properties-
Examples-- To configure the check: - --<module name="ExecutableStatementCount"/> -- - To configure the check with a threshold of 20 for constructor and - method definitions: - --<module name="ExecutableStatementCount"> - <property name="max" value="20"/> - <property name="tokens" value="CTOR_DEF,METHOD_DEF"/> -</module> - -- - Package-- com.puppycrawl.tools.checkstyle.checks.sizes - - -Parent Module-- TreeWalker - - - -FileLengthDescription-- Checks for long source files. - -- Rationale: If a source file becomes very long it is hard to understand. - Therefore long classes should usually be refactored into several individual - classes that focus on a specific task. - - -Properties- -
Examples-- To configure the check to accept files with up to 1500 lines: - --<module name="FileLength"> - <property name="max" value="1500"/> -</module> -- - Package-- com.puppycrawl.tools.checkstyle.checks.sizes - -Parent Module-- TreeWalker - - -LineLengthDescription-- Checks for long lines. - -- Rationale: Long lines are hard to read in printouts or if developers have - limited screen space for the source code, e.g. if the IDE displays additional - information like project tree, class hierarchy, etc. - - -Properties- -
Examples-- To configure the check to accept lines up to 120 characters long: - --<module name="LineLength"> - <property name="max" value="120"/> -</module> -- - To configure the check to ignore lines that begin with " * ", followed - by just one word, such as within a Javadoc comment: - --<module name="LineLength"> - <property name="ignorePattern" value="^ *\* *[^ ]+$"/> -</module> -- - Notes-
Package-- com.puppycrawl.tools.checkstyle.checks.sizes - -Parent Module-- TreeWalker - - -MethodLengthDescription-- Checks for long methods and constructors. - -- Rationale: If a method becomes very long it is hard to understand. Therefore - long methods should usually be refactored into several individual methods that - focus on a specific task. - - -Properties- -
Examples-- To configure the check: - --<module name="MethodLength"/> -- - To configure the check so that it accepts methods with at most 60 lines: - --<module name="MethodLength"> - <property name="tokens" value="METHOD_DEF"/> - <property name="max" value="60"/> -</module> -- - - - To configure the check so that it accepts methods with at most 60 lines, not counting - empty lines and single line comments: - --<module name="MethodLength"> - <property name="tokens" value="METHOD_DEF"/> - <property name="max" value="60"/> - <property name="countEmpty" value="false"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.sizes - -Parent Module-- TreeWalker - - - -AnonInnerLengthDescription-- Checks for long anonymous inner classes. - -- Rationale: If an anonymous inner class becomes very long - it is hard to understand and to see the flow of the method - where the class is defined. Therefore long anonymous inner - classes should usually be refactored into a named inner class. - See also Bloch, Effective Java, p. 93. - - -Properties- -
Examples-- To configure the check to accept files with up to 60 lines: - --<module name="AnonInnerLength"> - <property name="max" value="60"/> -</module> -- - Package-- com.puppycrawl.tools.checkstyle.checks.sizes - -Parent Module-- TreeWalker - - -ParameterNumberDescription-- Checks the number of parameters of a method or constructor. - - -Properties- -
Examples-- To configure the check: - --<module name="ParameterNumber"/> -- - To configure the check to allow 10 parameters for a method: - --<module name="ParameterNumber"> - <property name="max" value="10"/> - <property name="tokens" value="METHOD_DEF"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.sizes - -Parent Module-- TreeWalker - - |
-
-Copyright © 2002-2004 Oliver Burn. All rights Reserved. -
- - - diff --git a/docs/config_usage.html b/docs/config_usage.html deleted file mode 100644 index cacde963a..000000000 --- a/docs/config_usage.html +++ /dev/null @@ -1,328 +0,0 @@ - - - - -Checks for usage |
- |
-
-
|
-
-
-
- OneMethodPrivateFieldDescription- -- Checks that a private field is used in more than one method, constructor, or initializer. - -- Rationale: a private field used in only one method, constructor, or - initializer should be replaced by a local variable. - -Properties-
Examples-- To configure the check: - --<module name="usage.OneMethodPrivateField"/> -- - To configure the check to ignore fields whose name ends in Temp: - --<module name="usage.OneMethodPrivateField"> - <property name="ignoreFormat" value="Temp$"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.usage - - -Parent Module-- TreeWalker - - - -UnusedLocalVariableDescription- -- Checks that a local variable is used after its declaration. - - -Properties-
Examples-- To configure the check: - --<module name="usage.UnusedLocalVariable"/> -- - To configure the check to ignore variables whose name ends in Temp: - --<module name="usage.UnusedLocalVariable"> - <property name="ignoreFormat" value="Temp$"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.usage - - -Parent Module-- TreeWalker - - - -UnusedParameterDescription- -- Checks that a parameter is used. - - -Properties-
Examples-- To configure the check: - --<module name="usage.UnusedParameter"/> -- - To configure the check to ignore parameters whose name ends in Temp: - --<module name="usage.UnusedParameter"> - <property name="ignoreFormat" value="Temp$"/> -</module> -- - To configure the check to report unused catch parameters: - --<module name="usage.UnusedParameter"> - <property name="ignoreCatch" value="false"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.usage - - -Parent Module-- TreeWalker - - -UnusedPrivateFieldDescription- -- Checks that a private field is used. - - -Properties-
Examples-- To configure the check: - --<module name="usage.UnusedPrivateField"/> -- - To configure the check to ignore fields whose name ends in Temp: - --<module name="usage.UnusedPrivateField"> - <property name="ignoreFormat" value="Temp$"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.usage - - -Parent Module-- TreeWalker - - - -UnusedPrivateMethodDescription- -- Checks that a private method is used. - - -Properties-
Examples-- To configure the check: - --<module name="usage.UnusedPrivateMethod"/> -- - To configure the check to ignore methods whose name ends in Temp: - --<module name="usage.UnusedPrivateMethod"> - <property name="ignoreFormat" value="Temp$"/> -</module> -- - Notes- -
Package-- com.puppycrawl.tools.checkstyle.checks.usage - - -Parent Module-- TreeWalker - - - |
-
-Copyright © 2002-2004 Oliver Burn. All rights Reserved. -
- - - diff --git a/docs/config_whitespace.html b/docs/config_whitespace.html deleted file mode 100644 index fc630c108..000000000 --- a/docs/config_whitespace.html +++ /dev/null @@ -1,980 +0,0 @@ - - - - -Checks for whitespace |
- |
-
-
|
-
-
-
- EmptyForInitializerPadDescription- -- Checks the padding of an empty for initializer; that is whether white - space is required at an empty for initializer, or such white space is - forbidden. - No check occurs if there is a line wrap at the initializer, as in - --for ( - ; i < j; i++, j--) -- Properties-
Examples-- To configure the check: - --<module name="EmptyForInitializerPad"/> -- - To configure the check to require white space at an empty for iterator: - --<module name="EmptyForInitializerPad"> - <property name="option" value="space"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.whitespace - - -Parent Module-- TreeWalker - - -EmptyForIteratorPadDescription- -- Checks the padding of an empty for iterator; that is whether white - space is required at an empty for iterator, or such white space is - forbidden. - No check occurs if there is a line wrap at the iterator, as in - --for (Iterator foo = very.long.line.iterator(); - foo.hasNext(); - ) -- Properties-
Examples-- To configure the check: - --<module name="EmptyForIteratorPad"/> -- - To configure the check to require white space at an empty for iterator: - --<module name="EmptyForIteratorPad"> - <property name="option" value="space"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.whitespace - - -Parent Module-- TreeWalker - - -MethodParamPad-Description- -- Checks the padding between the identifier of a method definition, - constructor definition, method call, or constructor invocation; - and the left parenthesis of the parameter list. - That is, if the identifier and left parenthesis are on the same line, - checks whether a space is required immediately after the identifier or - such a space is forbidden. - If they are not on the same line, reports an error, unless configured to allow line breaks. - To allow linebreaks after the identifier, - set property allowLineBreaks to - true. - -Properties-
Examples-- To configure the check: - --<module name="MethodParamPad"/> -- - To configure the check to require a space - after the identifier of a method definition, except if the left - parenthesis occurs on a new line: - --<module name="MethodParamPad"> - <property name="tokens" value="METHOD_DEF"/> - <property name="option" value="space"/> - <property name="allowLineBreaks" value="true"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.whitespace - -Parent Module-- TreeWalker - - -NoWhitespaceAfter-Description- -- Checks that there is no whitespace after a token. More specifically, it checks - that it is not followed by whitespace, or (if linebreaks are allowed) all - characters on the line after are whitespace. To forbid linebreaks after a token, - set property allowLineBreaks to - false. - -Properties-
Examples-- To configure the check: - --<module name="NoWhitespaceAfter"/> -- - To configure the check to forbid linebreaks after a DOT token: - --<module name="NoWhitespaceAfter"> - <property name="tokens" value="DOT"/> - <property name="allowLineBreaks" value="false"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.whitespace - -Parent Module-- TreeWalker - - -NoWhitespaceBeforeDescription- -- Checks that there is no whitespace before a token. More specifically, it checks - that it is not preceded with whitespace, or (if linebreaks are allowed) all - characters on the line before are whitespace. To allow linebreaks before a token, - set property allowLineBreaks to - true. - -Properties-
Examples-- To configure the check: - --<module name="NoWhitespaceBefore"/> -- - To configure the check to allow linebreaks before a DOT token: - --<module name="NoWhitespaceBefore"> - <property name="tokens" value="DOT"/> - <property name="allowLineBreaks" value="true"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.whitespace - - -Parent Module-- TreeWalker - -OperatorWrapDescription- -- Checks the policy on how to wrap lines on operators. - -Properties-
Examples-- To configure the check: - --<module name="OperatorWrap"/> -- - To configure the check for the assignment operator, =, - at the end of a line: - --<module name="OperatorWrap"> - <property name="tokens" value="ASSIGN"/> - <property name="option" value="eol"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.whitespace - - -Parent Module-- TreeWalker - - - -ParenPadDescription- -- Checks the policy on the padding of parentheses; i.e. whether a space is - required after a left parenthesis and before a right parenthesis, or such spaces - are forbidden. - -Properties-
Examples-- To configure the check: - --<module name="ParenPad"/> -- - To configure the check to require spaces for the parentheses of constructor, - method, and super constructor calls: - --<module name="ParenPad"> - <property name="tokens" value="CTOR_CALL, METHOD_CALL, - SUPER_CTOR_CALL"/> - <property name="option" value="space"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.whitespace - - -Parent Module-- TreeWalker - - - -TypecastParenPad- -Description- -Checks the policy on the padding of parentheses for - typecasts. That is, whether a space is required after a left parenthesis - and before a right parenthesis, or such spaces are forbidden. - -Properties-
Examples-- To configure the check: - --<module name="TypecastParenPad"/> -- - To configure the check to require spaces: - --<module name="TypecastParenPad"> - <property name="option" value="space"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.whitespace - - -Parent Module-- TreeWalker - - - -TabCharacterDescription- -- Checks that there are no tab characters ('\t') in the - source code. - -- Rationale: - -
Example-- To configure the check: - --<module name="TabCharacter"/> -- Package-- com.puppycrawl.tools.checkstyle.checks.whitespace - - -Parent Module-- TreeWalker - -WhitespaceAfterDescription- -- Checks that a token is followed by whitespace. - -Properties-
Examples-- To configure the check: - --<module name="WhitespaceAfter"/> -- - To configure the check for whitespace only after COMMA and SEMI tokens: - --<module name="WhitespaceAfter"> - <property name="tokens" value="COMMA, SEMI"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.whitespace - - -Parent Module-- TreeWalker - -WhitespaceAroundDescription- -- Checks that a token is surrounded by whitespace. - -Properties-
Examples-- To configure the check: - --<module name="WhitespaceAround"/> -- - To configure the check for whitespace around the assignment operator, =: - --<module name="WhitespaceAround"> - <property name="tokens" value="ASSIGN"/> -</module> -- Package-- com.puppycrawl.tools.checkstyle.checks.whitespace - - -Parent Module-- TreeWalker - - |
-
-Copyright © 2002-2004 Oliver Burn. All rights Reserved. -
- - - diff --git a/docs/contributing.html b/docs/contributing.html deleted file mode 100644 index 3f98a2df7..000000000 --- a/docs/contributing.html +++ /dev/null @@ -1,136 +0,0 @@ - - - - -
- Contributing to Checkstyle- |
-
-
- |
-
|
- Contributing -
|
-
-
-
-
- Introduction- -- Hey, good to see you on this page. It means that you are - considering a contribution of your own work to the Checkstyle - project. We welcome anything: bugfixes, new check modules, unit - tests, documentation improvements, build process simplification, - etc. - - -- This document assumes you are working with the CVS version of - checkstyle and that you are familiar with some standard - development tools (CVS, - Ant, JUnit). - - - -Quality matters- -- The developer team of checkstyle is really a lazy bunch of - people. We try to avoid work as best as we can, but most of all - we try to avoid working on bugs that are reported by end users. - - -- To that end, we use a set of development tools that ensure that the - quality of our code is kept at a fairly high level. Like most projects - today, we use JUnit to test our code. However we do take this one - step further and measure the coverage of our unit tests using - Clover. This means it - is not sufficient to pass all tests, but the tests should ideally - execute each line in the code. The most recent Clover report is - available here. - - -- Besides using unit testing, we obviously also use checkstyle to check - it's own code. - - -- We have the build target gump in our - Ant buildfile that builds checkstyle, executes all tests, - and runs checkstyle on it's own code. - That target should pass without errors. - - -- If you add new end user features, remember to document them. - - - -Submitting your contribution- -- Once you have made sure that your changes pass the gump target, - and everthing is documented, you are ready to submit your work. - - -- If you have created new files, put them in a tgz file (or zip if you - are on Windows). If you have changed existing files, create a unified - diff using CVS. To do that, open a command line, cd to the home - directory of checkstyle (where build.xml is located) and execute - cvs diff -u > mychanges.patch. - - -- Create a new item in our - patch tracker - and add the tgz/zip/patch files you created. - Make sure the text in the tracker explains the purpose of your contribution. - When you create a tracker entry, a notification email about your contribution - will automatically be sent to the developer mailing list. - Be prepared to answer questions and do some polishing work. - - -- We are not only lazy but at times we are also busy with our day jobs. - This means that you might not always get an immediate answer. You are - not being ignored, and we value your work - we might just be too busy - to review your code, especially if it is a bit complex. If you don't - get a response within two weeks, feel free to send a reminder email about - your tracker item. - - - |
-
Copyright © 2002-2004 Oliver Burn. All rights Reserved.
- diff --git a/docs/gui_screenshot.png b/docs/gui_screenshot.png deleted file mode 100644 index 7b8c7a38b..000000000 Binary files a/docs/gui_screenshot.png and /dev/null differ diff --git a/docs/java.header b/docs/java.header deleted file mode 100644 index 00be82d45..000000000 --- a/docs/java.header +++ /dev/null @@ -1,18 +0,0 @@ -//////////////////////////////////////////////////////////////////////////////// -// checkstyle: Checks Java source code for adherence to a set of rules. -// Copyright (C) 2001-2004 Oliver Burn -// -// This library is free software; you can redistribute it and/or -// modify it under the terms of the GNU Lesser General Public -// License as published by the Free Software Foundation; either -// version 2.1 of the License, or (at your option) any later version. -// -// This library is distributed in the hope that it will be useful, -// but WITHOUT ANY WARRANTY; without even the implied warranty of -// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -// Lesser General Public License for more details. -// -// You should have received a copy of the GNU Lesser General Public -// License along with this library; if not, write to the Free Software -// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA -//////////////////////////////////////////////////////////////////////////////// diff --git a/docs/logo.png b/docs/logo.png deleted file mode 100644 index 2528031c5..000000000 Binary files a/docs/logo.png and /dev/null differ diff --git a/docs/mystyle.css b/docs/mystyle.css deleted file mode 100644 index 779b0bcd4..000000000 --- a/docs/mystyle.css +++ /dev/null @@ -1,77 +0,0 @@ -h1 { - font-family : monospace; - font-size : 28px; - font-weight : bold; - color : #aaaaaa; - background-color: #ffffff; - text-transform: capitalize; -} - -h2 { - text-transform: capitalize; -} - -h4.tip { - text-transform: capitalize; - text-align: center; -} - -td { - vertical-align:top; -} - -td.required { - text-align: center; -} - -tr.header { - background-color: Silver; - color:Black; - font-weight: bolder; - text-align: center; -} - -td.menu { - background-color: #eeeeee; - color:Black; - text-align: left; - white-space: nowrap; -} - -td.content { - width: 100%; -} - -*.body { - margin-left : 5%; - margin-right : 3%; -} - -img { - border: none; -} - -p.copyright { - text-align: center; -} - -span.code { - white-space: nowrap; - font-family: monospace; - font-weight: bold -} - -span.default { - white-space: nowrap; - font-family: monospace; -} - -div.tip { - margin-left : 5%; - margin-right : 5%; - padding-left: 2%; - padding-right: 2%; - background-color: Silver; - color:Black; - border: ridge; -} diff --git a/docs/optional.html b/docs/optional.html deleted file mode 100644 index 512920526..000000000 --- a/docs/optional.html +++ /dev/null @@ -1,77 +0,0 @@ - - - - -
- Optional Checks - Version @CHECKSTYLE_VERSION@- |
-
-
- |
-
-Core Checkstyle Checks are applicable to general Java coding style and require no -external libraries. An optional Check is for special applications or requires -additional libraries. There are are optional Checks for: -
--As with core Checks, optional Checks are configured as submodules of -TreeWalker. The shortened -name of an optional Check module must include the appropriate package -name prefix. For example, this is a configuration fragment -for Check com.puppycrawl.tools.checkstyle.checks.usage.UnusedLocalVariable: -
--<module name="usage.UnusedLocalVariable"/> -- -
-Consult the Checkstyle configuration manual -to learn how to integrate -optional Checks into the package configuration so that you can use fully shortened -names such as UnusedLocalVariable. -
--Optional checks are distributed in jar file -checkstyle-optional-@CHECKSTYLE_VERSION@.jar and, -in order to use an optional check, this jar file must be in the classpath. -For example, this is a command to run Checkstyle with a configuration -that contains optional checks: -
--java -classpath checkstyle-optional-@CHECKSTYLE_VERSION@.jar:checkstyle-all-@CHECKSTYLE_VERSION@.jar \ - com.puppycrawl.tools.checkstyle.Main \ - -c config.xml -r . --
-Please consult Command Line and -ANT Task documentation for further usage information. -
- -Copyright © 2002-2004 Oliver Burn. All rights Reserved.
- - diff --git a/docs/property_types.html b/docs/property_types.html deleted file mode 100644 index 75aee252f..000000000 --- a/docs/property_types.html +++ /dev/null @@ -1,300 +0,0 @@ - - - - -Checkstyle is configured using properties, which are string -representations. This document describes how these string representations are -mapped to typed properties.
- -This property represents an integer. The string representation is parsed -using the java.lang.Integer class.
- - -This property represents a string. The literal string representation is -used.
- - -This property represents a boolean. The default value is false. The following string representations will map to -true:
- -Anything else will map to false.
- - -This property represents a set of strings. The string representation is -parsed as a set of comma (',') separated strings.
- - -This property represents a set of integers. The string representation is -parsed as a set of comma (',') separated integers that are parsed using the -java.lang.Integer class.
- - -This property represents a regular expression. The string representation is -parsed using the excellent Jakarta -Regexp library.
- - -This property represents the policy for padding with white space. The -following table describes the valid options:
- -| Option | -Definition | -
| nospace | -Do not pad. For example, method(a, b); | -
| space | -Ensure padding. For example, method( a, b ); | -
This property represents the policy for wrapping lines on operators. The -following table describes the valid options:
- -| Option | -Definition | -
| nl | -The operator must be on a new line. For example:
-- someVariable = aBigVariableNameToMakeThings + "this may work" - + lookVeryInteresting; -- |
-
| eol | -The operator must be at the end of the line. For example:
-- someVariable = aBigVariableNameToMakeThings + "this may work" + - lookVeryInteresting; -- |
-
This property represents the policy for checking block statements. The -following table describes the valid options:
- -| Option | -Definition | -
| text | -Require that there is some text in the block. For example:
-
- catch (Exception ex) {
- // This is a bad coding practice
- }
-
- |
-
| stmt | -Require that there is a statement in the block. For example:
-
- finally {
- lock.release();
- }
-
- |
-
This property represents the policy for checking the placement of a left -curly brace ('{'). The following table describes the -valid options:
- -| Option | -Definition | -
| eol | -The brace must always be on the end of the line. For example:
-
- if (condition) {
- ...
-
- |
-
| nl | -The brace must always be on a new line. For example:
-
- if (condition)
- {
- ...
-
- |
-
| nlow | -If the brace will fit on the first line of the statement, taking into account maximum line length, then apply eol rule. Otherwise apply the nl rule. nlow is a mnemonic for "new line on wrap". For the example above Checkstyle will enforce:
-
- if (condition) {
- ...
-
- But for a statement spanning multiple lines, Checkstyle will enforce:
-
- if (condition1 && condition2 &&
- condition3 && condition4)
- {
- ...
-
- |
-
This property represents the policy for checking the placement of a right -curly brace ('}'). The following table describes the -valid options:
- -| Option | -Definition | -
| same | -The brace must be on the same line as the next statement. For example:
-
- try {
- ...
- } finally {
-
- |
-
| alone | -The brace must be alone on the line. For example:
-
- try {
- ...
- }
- finally {
-
- |
-
This property represents a Java scope. The valid options are:
- -This property represents the severity level of a check violation. The valid options are:
- -This property represents the policy for checking entity beans according -to whether the beans have bean-managed persistence, container-managed persistence, -or mixed persistence:
- -| Option | -Definition | -
| bean | -The beans have bean-managed persistence. | -
| container | -The beans have container-managed persistence. | -
| mixed | -The beans have mixed bean-managed and container-managed persistence. | -
Copyright © 2002-2004 Oliver Burn. All rights Reserved.
- - - diff --git a/docs/sun_checks.xml b/docs/sun_checks.xml deleted file mode 100644 index b0f098c42..000000000 --- a/docs/sun_checks.xml +++ /dev/null @@ -1,171 +0,0 @@ - - - - - -
- Writing your own Checks- |
-
-
- |
-
| - - - - - - - | - - -
-
- Overview-- OK, so you have finally decided to write your own Check. - Welcome aboard, this is really a fun thing to do. There are - actually two kinds of Checks, so before you can start, you have - to find out which kind of Check you want to implement. - - -The functionality of Checkstyle is implemented in - modules that can be plugged into Checkstyle. Modules can be containers - for other modules, i.e. they form a tree structure. The toplevel modules - that are known directly to the Checkstyle kernel (which is also a module - and forms the root of the tree) implement the FileSetCheck - interface. These are pretty simple to grasp: they take a set of input - files and fire error messages. - -Checkstyle provides a few FileSetCheck implementations - by default and one of them happens to be the TreeWalker. A - TreeWalker supports submodules that are derived from the Check - class. The TreeWalker operates by separately transforming each of the - Java input files into an abstract syntax tree and then handing the - result over to each of the Check submodules which in turn have a look at - a certain aspect of the tree. - - -Writing Checks-- - Most of the functionality of Checkstyle is implemented as - Checks. If you know how to write your own Checks, you can extend - Checkstyle according to your needs without having to wait for - the Checkstyle development team. You are about to become a - Checkstyle Expert. - - -- Suppose you have a convention that the number of methods in a - class should not exceed a certain limit, say 30. This rule makes - sense, a class should only do one thing and do it well. With a - zillion methods chances are that the class does more than one - thing. The only problem you have is that your convention is not - checked by Checkstyle, so you'll have to write your own Check - and plug it into the Checkstyle framework. - - -This chapter is organized as a tour that takes you - through the process step by step and explains both the theoretical - foundations and the Checkstyle - API along the way. - - -Java Grammar-- Every Java Program is structured into files, and each of these - files has a certain structure. For example, if there is a - package statement then it is the first line of the file that is - not comment or whitespace. After the package statement comes a - list of import statements, which is followed by a class or - interface definition, and so on. - -- If you have ever read an introductory level Java book you probably - knew all of the above. And if you have studied computer science, - you probably also know that the rules that specify the Java language - can be formally specified using a grammar (statement is simplified - for didactic purposes). - -- Tools exist which read a grammar definition and produce a parser - for the language that is specified in the grammar. In other - words, the output of the tool is a program that can transform a - stream of characters (a Java file) into a tree representation - that reflects the structure of the file. Checkstyle uses the - parser generator ANTLR but - that is an implementation detail you do not need to worry about - when writing Checks. Several other parser generators exist and - they all work well. - - - -The Checkstyle SDK gui-- Still with us? Great, you have mastered the basic theory so here - is your reward - a gui that displays the structure of a Java - source file. To run it type - -- java -classpath checkstyle-all-@CHECKSTYLE_VERSION@.jar \ - com.puppycrawl.tools.checkstyle.gui.Main -- - on the command line. Click the button at the bottom of the frame - and select a syntactically correct Java source file. The frame - will be populated with a tree that corresponds to the structure - of the Java source code. - - -
- In the leftmost column you can open and close branches - of the tree, the remaining columns display information about each node - in the tree. The second column displays a token type for each node. As - you navigate from the root of the tree to one of the leafs, you'll - notice that the token type denotes smaller and smaller units of your - source file, i.e. close to the root you might see the token type CLASS_DEF - (a node that represents a class definition) while you will see token - types like IDENT (an identifier) near the leaves of the tree. - -- We'll get back to the details in the other columns later, they - are important for implementing Checks but not for understanding - the basic concepts. For now it is sufficient to know that the - gui is a tool that lets you look at the structure of a Java - file, i.e. you can see the Java grammar 'in action'. - - - -Understanding the visitor pattern-- Ready for a bit more theory? The last bit - that is missing before you can start writing Checks is understanding - the Visitor pattern. - - -- When working with ASTs, a simple approach to define check operations - on them would be to add a check() method to the Class that defines - the AST nodes. For example, our AST type could have a method - checkNumberOfMethods(). Such an approach would suffer from a few - serious drawbacks. Most importantly, it does not provide an extensible - design, i.e. the Checks have to be known at compile time; there is no - way to write plugins. - - -Hence Checkstyle's AST classes do not have any - methods that implement checking functionality. Instead, - Checkstyle's TreeWalker - takes a set of objects that conform to a Check - interface. OK, you're right - actually it's not an interface - but an abstract class to provide some helper methods. A Check provides - methods that take an AST as an argument and perform the checking process - for that AST, most prominently visitToken(). - -It is important to understand that the individual - Checks do no drive the AST traversal. Instead, the TreeWalker initiates - a recursive descend from the root of the AST to the leaf nodes and calls - the Check methods. The traversal is done using a depth-first - algorithm. - -Before any visitor method is called, the TreeWalker - will call beginTree() to give the Check a chance to do - some initialization. Then, when performing the recursive descend from - the root to the leaf nodes, the visitToken() - method is called. Unlike the basic examples in the pattern book, there - is a visitToken() counterpart called leaveToken(). The TreeWalker will call that - method to signal that the subtree below the node has been processed and - the TreeWalker is backtracking from the node. After the root node has - been left, the TreeWalker will call finishTree(). - -- If you'd like to learn more about the Visitor pattern you should - grab a copy of the Gof - Design - Patterns book. - - - -Visitor in action-- Let's get back to our example and start writing code - that's why - you came here, right? - When you fire up the Checkstyle GUI and look at a few source - files you'll figure out pretty quickly that you are mainly - interested in the number of tree nodes of type METHOD_DEF. The - number of such tokens should be counted separately for each - CLASS_DEF / INTERFACE_DEF. - - -- Hence we need to register the Check for the token types - CLASS_DEF and INTERFACE_DEF. The TreeWalker will only call - visitToken for these token types. Because the requirements of - our tasks are so simple, there is no need to implement the other - fancy methods, like finishTree(), etc., so here is our first - shot at our Check implementation: - - -
- package com.mycompany.checks;
-
- import com.puppycrawl.tools.checkstyle.api.*;
-
- public class MethodLimitCheck extends Check
- {
- private int max = 30;
-
- public int[] getDefaultTokens()
- {
- return new int[]{TokenTypes.CLASS_DEF, TokenTypes.INTERFACE_DEF};
- }
-
- public void visitToken(DetailAST ast)
- {
- // find the OBJBLOCK node below the CLASS_DEF/INTERFACE_DEF
- DetailAST objBlock = ast.findFirstToken(TokenTypes.OBJBLOCK);
-
- // count the number of direct children of the OBJBLOCK
- // that are METHOD_DEFS
- int methodDefs = objBlock.getChildCount(TokenTypes.METHOD_DEF);
-
- // report error if limit is reached
- if (methodDefs > max) {
- log(ast.getLineNo(),
- "too many methods, only " + max + " are allowed");
- }
- }
- }
-
-
-
- Navigating the Abstract Syntax Tree (AST)-- In the example above you already saw that the DetailsAST class - provides utility methods to extract information from the tree, like - getChildCount(). By now you have probably consulted the api - documentation and found that DetailsAST additionally provides methods - for navigating around in the syntax tree, like finding the next - sibling of a node, the children of a node, the parent of a node, etc. - - -- These methods provide great power for developing complex - Checks. Most of the Checks that Checkstyle provides by default - use these methods to analyze the environment of the ASTs that - are visited by the TreeWalker. Don't abuse that feature for - exploring the whole tree, though. Let the TreeWalker drive the - tree traversal and limit the visitor to the neighbours of a - single AST. - - - -Defining Check Properties-- - Ok Mr. Checkstyle, that's all very nice but in my company we - have several projects, and each has another number of allowed - methods. I need to control my Check through properties, so where - is the API to do that? - - -- Well, the short answer is, there is no API. It's magic. Really! - - -- If you need to make something configurable, just add a setter method - to the Check: - - -
- public class MethodLimitCheck extends Check
- {
- // code from above omitted for brevity
-
- public void setMax(int limit)
- {
- max = limit;
- }
- }
-
-
- - With this code added, you can set the property max for the MethodLimitCheck module in the - configuration file. It doesn't get any simpler than that. The secret is - that Checkstyle uses JavaBean introspection to set the JavaBean - properties. That works for all primitive types like boolean, - int, long, etc., plus Strings, plus arrays of these types. - - - -Logging errors-- Detecting errors is one thing, presenting them to the user is - another. To do that, the Check base class provides several log - methods, the simplest of them being Check.log(String). In your - Check you can simply use a verbatim error string like in log("Too many methods, only " + mMax + - " are allowed"); as the argument. That will - work, but it's not the best possible solution if your Check is - intended for a wider audience. - - -- If you are not living in a country where people speak English, - you may have noticed that Checkstyle writes internationalized - error messages, for example if you live in Germany the error - messages are German. The individual Checks don't have to do - anything fancy to achieve this, it's actually quite easy and the - Checkstyle framework does most of the work. - - -- To support internationalized error messages, you need to create - a message.properties file alongside your Check class, i.e. the - Java file and the properties files should be in the same - directory. Add a symbolic error code and an English - representation to the messages.properties. The file should - contain the following line: too.many.methods=Too many methods, only {0} are - allowed. Then replace the verbatim error message with - the symbolic representation and use one of the log helper - methods to provide the dynamic part of the message (mMax in this - case): log("too.many.methods", - mMax);. Please consult the documentation of Java's MessageFormat - to learn about the syntax of format strings (especially about - those funny numbers in the translated text). - - -- Supporting a new language is very easy now, simply create a new - messages file for the language, e.g. messages_fr.properties to - provide french error messages. The correct file will be chosen - automatically, based on the language settings of the user's - operating system. - - - -Integrate your Check-- The great final moment has arrived, you are about to run your - Check. To integrate your Check, add a new subentry under the - TreeWalker module of your configuration file. Use the full - classname of your Check class as the name of the module. - Your configuration file should look something like this: - - -- <?xml version="1.0"?> - <!DOCTYPE module PUBLIC - "-//Puppy Crawl//DTD Check Configuration 1.2//EN" - "http://www.puppycrawl.com/dtds/configuration_1_2.dtd"> - <module name="Checker"> - <module name="TreeWalker"> - - <!-- your standard Checks that come with Checkstyle --> - <module name="UpperEll"/> - <module name="MethodLength"/> - - <!-- your Check goes here --> - <module name="com.mycompany.checks.MethodLimitCheck"> - <property name="max" value="45"/> - </module> - </module> - </module> -- - - To run the new Check on the command line compile your Check, - create a jar that contains the classes and property files, - e.g. mycompanychecks.jar. Then run - (with the path separator adjusted to your platform): - -- java -classpath mycompanychecks.jar:checkstyle-all-@CHECKSTYLE_VERSION@.jar \ - com.puppycrawl.tools.checkstyle.Main \ - -c config.xml -r . -- - - Did you see all those errors about "too many methods" - flying over your screen? Congratulations. You can now consider - yourself a Checkstyle expert. Go to your fridge. Have a beer. - - -- Please consult the Checkstyle - configuration manual to learn how to integrate your Checks - into the package configuration so that you can use MethodLimit instead of the full class name. - - - -Limitations-- OK, so you have written your first Check, and you have found - several flaws in many of your programs. You now know that your - boss does not follow the coding conventions he wrote. And you - know that you are the king of the world. To become a programming - god, you want to write your second Check - now wait, first you - should know what your limits are. - - -- There are basically only two of them: - -
- This means that you cannot implement some of the code inspection - features that are available in advanced IDEs like IntelliJ IDEA. For - example you will not be able to implement a Check that finds - redundant type casts or unused public methods. - - - - -Writing FileSetChecks- -Writing a FileSetCheck is pretty straightforward: Just - inherit from AbstractFileSetCheck - and implement the process(File[] files) method and you're - done. A very simple example could fire an error if the number of files - that are passed in exceeds a certain limit. Here is a FileSetCheck that does just that: - -
- package com.mycompany.checks;
-
- import java.io.File;
- import com.puppycrawl.tools.checkstyle.api.*;
-
- public class LimitImplementationFiles
- extends AbstractFileSetCheck
- {
- private int max = 100;
-
- public void setMax(int aMax)
- {
- max = aMax;
- }
-
- public void process(File[] files)
- {
- if (files != null && files.length > max) {
-
- // figure out the file that contains the error
- final String path = files[max].getPath();
-
- // message collector is used to collect error messages,
- // needs to be reset before starting to collect error messages
- // for a file.
- getMessageCollector().reset();
-
- // message dispatcher is used to fire AuditEvents
- MessageDispatcher dispatcher = getMessageDispatcher();
-
- // signal start of file to AuditListeners
- dispatcher.fireFileStarted(path);
-
- // log the message
- log(0, "max.files.exceeded", new Integer(max));
-
- // you can call log() multiple times to flag multiple
- // errors in the same file
-
- // fire the errors for this file to the AuditListeners
- fireErrors(path);
-
- // signal end of file to AuditListeners
- dispatcher.fireFileFinished(path);
- }
- }
- }
-
- - - Note that the configuration via bean introspection also applies - here. By implementing the setMax() method the FileSetCheck - automatically makes "max" a legal configuration - parameter that you can use in the Checkstyle configuration file. - - -- There are virtually no limits what you can do in - FileSetChecks. The craziest ideas we've had so far are: - -
Huh? I can't figure it out!-- That's probably our fault, and it means that we have to provide - better documentation. Please do not hesitate to ask questions on - the user mailing list, this will help us to improve this - document. Please ask your questions as precisely as possible. - We will not be able to answer questions like "I want to - write a Check but I don't know how, can you help me?". Tell - us what you are trying to do (the purpose of the Check), what - you have understood so far, and what exactly you are getting stuck - on. - - - -Contributing-- We need your help to keep improving Checkstyle. - - Whenever you write a Check or FileSetCheck that you think is - generally useful, please consider - contributing it to the - Checkstyle community and submit it for inclusion in the next - release of Checkstyle. - - - - |
-
Copyright © 2002-2004 Oliver Burn. All rights Reserved.
- diff --git a/docs/writingfilters.html b/docs/writingfilters.html deleted file mode 100644 index f39ed128a..000000000 --- a/docs/writingfilters.html +++ /dev/null @@ -1,164 +0,0 @@ - - - - -Writing your own Filters |
- |
-
|
- - Overview - -- Writing Filters - -- Using Filters - -- Huh? - -- Contributing - - |
-
- Overview-- A Checker has a set of Filters - that decide which audit events the Checker reports through its listeners. - Interface Filter and class FilterSet - are intended to support general AuditEvent filtering using a set of Filters. - - - A Filter has boolean method accept(AuditEvent) - that returns true if the Filter accepts the - AuditEvent parameter and returns false if the Filter - rejects it. - -- A FilterSet is a particular Filter - that contains a set of Filters. A FilterSet accepts an - AuditEvent if and only if - all Filters in the set accept the AuditEvent. - -- Here is a UML diagram for interface Filter - and class FilterSet. - -
-
- Writing Filters- -- The Filter that we demonstrate here rejects audit events for files whose name matches a - regular expression. - In order to enable the specification of the file name pattern as a property in a configuration file, - the Filter is an - AutomaticBean - with mutator method setFiles(String) that receives the file name pattern. - An AutomaticBean uses JavaBean introspection to set JavaBean properties such as - files. - - -
-package com.mycompany.filters;
-
-import org.apache.regexp.RE;
-import org.apache.regexp.RESyntaxException;
-
-import com.puppycrawl.tools.checkstyle.api.AuditEvent;
-import com.puppycrawl.tools.checkstyle.api.AutomaticBean;
-import com.puppycrawl.tools.checkstyle.api.Filter;
-import com.puppycrawl.tools.checkstyle.api.Utils;
-
-public class FilesFilter
- extends AutomaticBean
- implements Filter
-{
- private RE mFileRegexp;
-
- public FilesFilter()
- throws RESyntaxException
- {
- setFiles("^$");
- }
-
- public boolean accept(AuditEvent aEvent)
- {
- final String fileName = aEvent.getFileName();
- return ((fileName == null) || !mFileRegexp.match(fileName));
- }
-
- public void setFiles(String aFilesPattern)
- throws RESyntaxException
- {
- mFileRegexp = Utils.getRE(aFilesPattern);
- }
-}
-
- Using Filters- -- To incorporate a Filter in the filter set for a Checker, - include a module element for the Filter in the - configuration file. For example, to configure a Checker - so that it uses custom filter FilesFilter to prevent reporting of - audit events for files whose name contains "Generated", include the following module in the - configuration file: - - -- <module name="com.mycompany.filters.FilesFilter"> - <property name="files" value="Generated"/> - </module> -- - Huh? I can't figure it out!-- That's probably our fault, and it means that we have to provide better - documentation. Please do not hesitate to ask questions on the user mailing list, - this will help us to improve this document. Please ask your questions as - precisely as possible. We will not be able to answer questions like "I want - to write a filter but I don't know how, can you help me?". Tell us - what you are trying to do (the purpose of the filter), what you have - understood so far, and what exactly you are getting stuck on. - - -Contributing-- We need your help to keep improving Checkstyle. - - Whenever you write a filter that you think is generally useful, please - consider contributing it to the Checkstyle - community and submit it for inclusion in the next release of Checkstyle. - - - - |
-
-Copyright © 2002-2004 Oliver Burn. All rights Reserved. -
- - diff --git a/docs/writinglisteners.html b/docs/writinglisteners.html deleted file mode 100644 index 94653eab3..000000000 --- a/docs/writinglisteners.html +++ /dev/null @@ -1,369 +0,0 @@ - - - - -Writing your own Listeners |
- |
-
|
- - Overview - - -- Using Listeners - -- Examples - -
- Huh? - -- Contributing - - |
-
- Overview-- A Checkstyle listener monitors the progress of a Checker - during the audit of files. The Checker notifies its - attached listeners of significant events such as the start of the audit of a - file and the logging of a Check error, and the listeners respond appropriately. - Any number of listeners can be attached to a - Checker. An audit always adds one of the distribution listeners, DefaultLogger - or XMLLogger, - to report events. A DefaultLogger produces simple text - output for the events it receives, and a XMLLogger - produces an XML document for its events. - -- Listeners DefaultLogger and - XMLLogger are sufficient for most Checkstyle users, but you may find a - need for a custom listener. For example, a user has requested verbose output of - progress information during a Checkstyle run. Another user would like to filter - error events. This document explains how to write listeners for such tasks and - how to integrate them in a Checker module. It also describes two custom - listeners that are inspired by ANT listeners: a listener that is a wrapper for - the Jakarta Commons Logging API, and a listener that sends its results via email. - -- A listener is an implementation of the AuditListener - interface. During an audit, a Checker informs its - attached AuditListeners of six kinds of events: audit - started/ended, file started/ended, and logging of an error/exception. - -- An audit passes an event to a listener as an AuditEvent. - A file-related AuditEvent contains the name of that - file. An AuditEvent for error logging has a message, a - severity level, a message source such as the name of a Check, - and file line and column numbers that may be relevant to the error. The - notification of an exception to a AuditListener - includes an error AuditEvent and the details of the - exception. Here is a UML diagram for classes AuditListener - and AuditEvent. - -
-
- Writing Listeners- -- A custom listener is an implementation of the AuditListener - interface. If the listener has properties that can be set from a configuration, the listener must extend - AutomaticBean. - An AutomaticBean uses JavaBean introspection to set JavaBean properties. - -- The custom listener that we demonstrate here is a verbose listener that simply - prints each event notification to an output stream, and reports the number of - errors per audited file and the total number of errors. The default output stream is - System.out. In order to enable the specification of output to a file - through property file, - the class extends AutomaticBean and defines method - setFile(String). - - -
-package com.mycompany.listeners;
-
-import java.io.FileNotFoundException;
-import java.io.FileOutputStream;
-import java.io.OutputStream;
-import java.io.PrintWriter;
-
-import com.puppycrawl.tools.checkstyle.api.AuditEvent;
-import com.puppycrawl.tools.checkstyle.api.AuditListener;
-import com.puppycrawl.tools.checkstyle.api.AutomaticBean;
-import com.puppycrawl.tools.checkstyle.api.SeverityLevel;
-
-public class VerboseListener
- extends AutomaticBean
- implements AuditListener
-{
- private PrintWriter mWriter = new PrintWriter(System.out);
- private boolean mCloseOut = false;
- private int mTotalErrors;
- private int mErrors;
-
- public void setFile(String aFileName)
- throws FileNotFoundException
- {
- final OutputStream out = new FileOutputStream(aFileName);
- mWriter = new PrintWriter(out);
- mCloseOut = true;
- }
-
- public void auditStarted(AuditEvent aEvt)
- {
- mTotalErrors = 0;
- mWriter.println("Audit started.");
- }
-
- public void auditFinished(AuditEvent aEvt)
- {
- mWriter.println("Audit finished. Total errors: " + mTotalErrors);
- mWriter.flush();
- if (mCloseOut) {
- mWriter.close();
- }
- }
-
- public void fileStarted(AuditEvent aEvt)
- {
- mErrors = 0;
- mWriter.println(
- "Started checking file '" + aEvt.getFileName() + "'.");
- }
-
- public void fileFinished(AuditEvent aEvt)
- {
- mWriter.println("Finished checking file '" + aEvt.getFileName()
- + "'. Errors: " + mErrors);
- }
-
- public void addError(AuditEvent aEvt)
- {
- printEvent(aEvt);
- if (SeverityLevel.ERROR.equals(aEvt.getSeverityLevel())) {
- mErrors++;
- mTotalErrors++;
- }
- }
-
- public void addException(AuditEvent aEvt, Throwable aThrowable)
- {
- printEvent(aEvt);
- aThrowable.printStackTrace(System.out);
- mErrors++;
- mTotalErrors++;
- }
-
- private void printEvent(AuditEvent aEvt)
- {
- mWriter.println("Logging error -"
- + " file: '" + aEvt.getFileName() + "'"
- + " line: " + aEvt.getLine()
- + " column: " + aEvt.getColumn()
- + " severity: " + aEvt.getSeverityLevel()
- + " message: " + aEvt.getMessage()
- + " source: " + aEvt.getSourceName());
- }
-}
-
- - A listener that filters error events could perform the filtering in methods - addError and addException. As further examples - of listeners, CommonsLoggingListener - reports its events through the Commons Logging API, and MailLogger - e-mails the audit report of a DefaultLogger. - - -Using Listeners- -- To incorporate a custom listener in the set of listeners for a Checker, - include a module element for the listener in the - configuration file. For example, to configure a Checker - so that it uses custom listener VerboseListener to print audit messages - to a file named "audit.txt", include the following module in the - configuration file: - - -- <module name="com.mycompany.listeners.VerboseListener"> - <property name="file" value="audit.txt"/> - </module> -- - - Here is a truncated example of audit output from a - VerboseListener: - - -- Audit started. - Started checking file 'CommonsLoggingListener.java'. - Finished checking file 'CommonsLoggingListener.java'. Errors: 0 - Started checking file 'MailLogger.java'. - Finished checking file 'MailLogger.java'. Errors: 0 - Started checking file 'VerboseListener.java'. - Logging error - file: 'VerboseListener.java' line: 23 ... - Finished checking file 'VerboseListener.java'. Errors: 1 - Audit finished. Total errors: 1 -- - Examples-- This section describes two examples based on ANT listeners. The first listener, - CommonsLoggingListener, hands off events to the Jakarata - Commons Logging façade and the second, MailLogger, - sends a report of an audit via e-mail. The discussion of these examples and how - to use them is derived from material in "Java - Development with Ant" by Eric Hatcher and Steve Loughran, an excellent - ANT book. - - CommonsLoggingListener-- Jakarata Commons - Logging provides a façade for logging tools log4j, - Avalon LogKit, - J2SE 1.4, and others. Checkstyle listener - CommonsLoggingListener responds to an AuditEvent by handing it off to the - current Commons Logging Log. - -- The source code for CommonsLoggingListener is in - distribution directory contrib/examples/listeners. - Notice that each AuditListener method that receives an - AuditEvent calls a method for the Commons Logging log level corresponding - to the Checkstyle SeverityLevel of the - AuditEvent. - -- The easiest way to use CommonsLoggingListener is to - include checkstyle-all-@CHECKSTYLE_VERSION@.jar in - the classpath because that jar file contains all the Commons Logging classes. - The default Log under J2SE 1.4 is wrapper class Jdk14Logger. - Under earlier Java versions, the default Log is a simple wrapper class, SimpleLog. - Both default logging tools can be used directly from Commons Logging; if you - need to use other tools such as log4j, then you must include the appropriate jar - file(s) in the classpath. - -- Logging configuration details for Jakarta Commons Logging are in the documentation. - As a simple example, assume that log4j.jar is in - the classpath and the following log4j.properties - file is in the current directory: - -- # Set root logger level to INFO and its only appender to A1. - log4j.rootLogger=INFO, A1 - - # A1 is set to be a ConsoleAppender. - log4j.appender.A1=org.apache.log4j.ConsoleAppender - - # A1 uses PatternLayout. - log4j.appender.A1.layout=org.apache.log4j.PatternLayout - log4j.appender.A1.layout.ConversionPattern=%-5p %c %x- %m%n -- - Running a Checkstyle audit with a CommonsLoggingListener - yields this (abbreviated) output: - -- INFO com.puppycrawl...Checker - Audit started. - INFO com.puppycrawl...Checker - File "CommonsLoggingListener.java" started. - INFO com.puppycrawl...Checker - File "CommonsLoggingListener.java" finished. - INFO com.puppycrawl...Checker - File "MailLogger.java" started. - INFO com.puppycrawl...Checker - File "MailLogger.java" finished. - INFO com.puppycrawl...Checker - File "VerboseListener.java" started. - ERROR com.puppycrawl...ParenPadCheck - Line: 23 Column: 28 ... - INFO com.puppycrawl...Checker - File "VerboseListener.java" finished. - INFO com.puppycrawl...Checker - Audit finished. -- - MailLogger-- MailLogger sends an audit report in an email message. - The listener uses a DefaultLogger to prepare the text - of the message. The listener obtains other message - parameters such as to and subject - from environment properties that can be read from a properties file. - -- The source code for CommonsLoggingListener is in - distribution directory contrib/examples/listeners. - This implementation uses the JavaMail API - as the mail system, and you must include appropriate jar files in the classpath. - -- As an example of using MailLogger, - set system property -DMailLogger.properties.file=MailLogger.properties, - so that MailLogger reads message parameters from file - MailLogger.properties of the current directory: - -- MailLogger.from=user@example.org - MailLogger.failure.to=user@example.org - MailLogger.success.to=user@example.org - MailLogger.mailhost=localhost -- Huh? I can't figure it out!-- That's probably our fault, and it means that we have to provide better - documentation. Please do not hesitate to ask questions on the user mailing list, - this will help us to improve this document. Please ask your questions as - precisely as possible. We will not be able to answer questions like "I want - to write a listener but I don't know how, can you help me?". Tell us - what you are trying to do (the purpose of the listener), what you have - understood so far, and what exactly you are getting stuck on. - - -Contributing-- We need your help to keep improving Checkstyle. - - Whenever you write a listener that you think is generally useful, please - consider contributing it to the Checkstyle - community and submit it for inclusion in the next release of Checkstyle. - - - - |
-
-Copyright © 2002-2004 Oliver Burn. All rights Reserved. -
- - diff --git a/docs/xmllogger.dtd b/docs/xmllogger.dtd deleted file mode 100644 index d6d4579d5..000000000 --- a/docs/xmllogger.dtd +++ /dev/null @@ -1,17 +0,0 @@ - - - - - - - - - - -
-