447 lines
21 KiB
HTML
447 lines
21 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
|
|
<html>
|
|
<head>
|
|
<title>Checkstyle Core Engine - Version @CHECKSTYLE_VERSION@</title>
|
|
<link rel="stylesheet" type="text/css" href="mystyle.css">
|
|
</head>
|
|
|
|
<body>
|
|
<h1>Checkstyle Core Engine - Version @CHECKSTYLE_VERSION@</h1>
|
|
|
|
<p>Authors: <a href="mailto:checkstyle@puppycrawl.com">Oliver Burn</a>, <a href="mailto:lars.kuehne@planet-interkom.de">Lars Kühne</a></p>
|
|
|
|
<h2>Introduction</h2>
|
|
<p>This document describes the core engine of Checkstyle, including what checks it performs and what can be configured. The engine can be executed via different <a href="index.html#related">interfaces</a>. The standard distribution includes support for:
|
|
|
|
<ul>
|
|
<li><a href="http://jakarta.apache.org/ant/">ANT Task</a> - see <a href="anttask.html">anttask.html</a> for more information.</li>
|
|
<li>Command line tool - see <a href="cmdline.html">cmdline.html</a> for more information.</li>
|
|
</ul>
|
|
|
|
<!-- System requirements -->
|
|
<h2>System Requirements</h2>
|
|
<p>To run checkstyle you will need:</p>
|
|
<ul>
|
|
<li>JRE 1.2 or later</li>
|
|
<li><a href="http://www.antlr.org">ANTLR 2.7.1</a> (JAR supplied in binary distribution)</li>
|
|
<li><a href="http://jakarta.apache.org/regexp">Regexp 1.2</a> (JAR supplied in binary distribution)</li>
|
|
</ul>
|
|
|
|
<p>Checkstyle has been tested using:</p>
|
|
<ul>
|
|
<li>JRE1.4.0 on Red Hat Linux 7.2</li>
|
|
<li>JRE1.3.1 on Windows NT 4, Windows 2000, Windows XP</li>
|
|
<li>JRE1.2.2 on Windows 2000</li>
|
|
</ul>
|
|
|
|
|
|
<h2>What checkstyle checks</h2>
|
|
|
|
<p>Checkstyle operates on a set of syntactically correct Java files. Checkstyle will report syntax errors, but the focus of the tool is not to provide perfect error messages for Java syntax errors - we leave that to the compiler vendors.</p>
|
|
|
|
<p>For each Java file, Checkstyle will check the following:</p>
|
|
|
|
<h3><a name="imports">Imports</a></h3>
|
|
|
|
<p>Checks for illegal package prefixes in import statements. The prefix <span class="code">sun</span> is the default, since programs that contain direct calls to the <span class="code">sun.*</span> packages are <a href="http://java.sun.com/products/jdk/faq/faq-sun-packages.html">not 100% Pure Java</a>.</p>
|
|
|
|
<p>Checks for import statements that are not used. It will warn about wild-card imports like <span class="code">import java.io.*;</span>. It will also warn about duplicate import statements.</p>
|
|
|
|
<p>Removing unused import statements reduces unnecessary dependencies in a code base. This feature can be turned off.</p>
|
|
|
|
|
|
|
|
<h3>Javadoc tags</h3>
|
|
|
|
<p>Checks that the following constructs have a Javadoc comment:</p>
|
|
<ul>
|
|
<li>class</li>
|
|
<li>interface</li>
|
|
<li>variable</li>
|
|
<li>method</li>
|
|
</ul>
|
|
|
|
<p>You can require that a <span class="code">package.html</span> file exists for each package. This check is turned off by default.</p>
|
|
|
|
<p>Javadoc comments for class and interface declarations are checked to ensure that the <span class="code">@author</span> tag exists. This can be turned off.</p>
|
|
|
|
<p>You can control the visibility scope where Javadoc comments are checked. For example, you can check Javadoc code only for <span class="code">public</span> and <span class="code">protected</span> variables, methods, interfaces and class definitions. Scoping rules apply, in the above example a public method in a package visible class is not checked. You can also completely turn off all checking for Javadoc comments.</p>
|
|
|
|
<p>Javadoc comments for methods are checked to ensure that the following tags exist (if required):</p>
|
|
<ul>
|
|
<li><span class="code">@return</span></li>
|
|
<li><span class="code">@param</span></li>
|
|
<li><span class="code">@throws</span> or <span class="code">@exception</span></li>
|
|
<li><span class="code">@see</span></li>
|
|
</ul>
|
|
|
|
<p>For example the following is valid:</p>
|
|
<pre>
|
|
/**
|
|
* 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)
|
|
</pre>
|
|
|
|
<p>By default an unused <span class="code">@throws</span> tag is reported as error. It is possible to enable checking to determine if the exception is a subclass of <span class="code">java.lang.RuntimeException</span>. This supports the convention in the <a href="http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#throwstag">Sun Javadoc Guidelines</a> and the "Effective Java" book. By default the check is off as it requires the classpath to be configured.</p>
|
|
|
|
<div class="tip">
|
|
<h4 class="tip">Tip</h4>
|
|
<p>It can be extremely painful writing or duplicating Javadoc for a method required for an interface. Hence checkstyle supports using the convention of using a single <span class="code">@see</span> tag instead of all the other tags. For example, if the previous method was implementing a method required by the <span class="code">com.puppycrawl.tools.checkstyle.Verifier</span> interface, then the Javadoc could be done as:</p>
|
|
|
|
<pre>
|
|
/** @see com.puppycrawl.tools.checkstyle.Verifier **/
|
|
public int checkReturnTag(final int aTagIndex,
|
|
JavadocTag[] aTags,
|
|
int aLineNo)
|
|
</pre>
|
|
</div>
|
|
|
|
<h3><a name="curly">Curly Braces</a></h3>
|
|
<p>Checks for the correct placement of left curly braces <span class="code">'{'</span>. The check can be configured with the following options:</p>
|
|
<a name="lcurlyopt"></a>
|
|
<table border="1" summary="left curly options">
|
|
<tr class="header">
|
|
<td>Option</td>
|
|
<td>Definition</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code">ignore</span></td>
|
|
<td>Ignore the placement of the brace.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code">eol</span></td>
|
|
<td>The brace must always be on the end of the line. For example:
|
|
<pre>
|
|
if (condition) {
|
|
...
|
|
</pre>
|
|
This is the default value.
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code">nl</span></td>
|
|
<td>The brace must always be on a new line. For example:
|
|
<pre>
|
|
if (condition)
|
|
{
|
|
...
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code">nlow</span></td>
|
|
<td>If the brace will fit on the first line of the statement, taking into account maximum line length, then apply <span class="code">eol</span> rule. Otherwise apply the <span class="code">nl</span> rule. <span class="code">nlow</span> is a mnemonic for "new line on wrap". For the example above Checkstyle will enforce:
|
|
<pre>
|
|
if (condition) {
|
|
...
|
|
</pre>
|
|
But for a statement spanning multiple lines, Checkstyle will enforce:
|
|
<pre>
|
|
if (condition1 && condition2 &&
|
|
condition3 && condition4)
|
|
{
|
|
...
|
|
</pre>
|
|
|
|
</tr>
|
|
</table>
|
|
|
|
<p><a name="lcurlyother"></a>The check can be tailored for types, methods and others. What is included in others are the keywords <span class="code">switch</span>, <span class="code">while</span>, <span class="code">for</span>, <span class="code">do</span>, <span class="code">if</span>, <span class="code">else</span>, <span class="code">synchronized</span>, <span class="code">try</span>, <span class="code">catch</span>, <span class="code">finally</span> and <span class="code">static</span>.</p>
|
|
|
|
<p><a name="rcurly"></a>There is also a check for the correct placement of right curly braces <span class="code">'}'</span> with the keywords <span class="code">else</span>, <span class="code">catch</span> and <span class="code">finally</span>. The check can be configured with the following options:</p>
|
|
<a name="rcurlyopt"></a>
|
|
<table border="1" summary="right curly options">
|
|
<tr class="header">
|
|
<td>Option</td>
|
|
<td>Definition</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code">ignore</span></td>
|
|
<td>Ignore the placement of the brace.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code">same</span></td>
|
|
<td>The brace must be on the same line as the next statement. For example:
|
|
<pre>
|
|
try {
|
|
...
|
|
} finally {
|
|
</pre>
|
|
This is the default value.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code">alone</span></td>
|
|
<td>The brace must be alone on the line. For example:
|
|
<pre>
|
|
try {
|
|
...
|
|
}
|
|
finally {
|
|
</pre>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<h3><a name="length">Long Lines</a></h3>
|
|
<p>Checks for lines that are longer than a specified length. The default is <span class="default">"80"</span>. This can be turned off for <code>import</code> statements or for lines that match a regular expression.</p>
|
|
|
|
<h3><a name="methodLength">Method Body Length</a></h3>
|
|
<p>Checks for method bodies that are longer than a specified number of lines. The lines are counted from the opening brace <span class="code">'{'</span> to the closing brace <span class="code">'}'</span>. The default is <span class="default">"150"</span>.
|
|
|
|
<h3><a name="constructorLength">Constructor Body Length</a></h3>
|
|
<p>Checks for constructor bodies that are longer than a specified number of lines. The lines are counted from the opening brace <span class="code">'{'</span> to the closing brace <span class="code">'}'</span>. The default is <span class="default">"150"</span>.
|
|
|
|
<h3><a name="fileLength">File Length</a></h3>
|
|
<p>Checks for files that are longer than a specified number of lines. The default is <span class="default">"2000"</span>.</p>
|
|
|
|
<h3>Tab characters</h3>
|
|
<p>Checks for lines that contain tab (<code>'\t'</code>) characters. This can be turned off.</p>
|
|
|
|
<h3><a name="todo">To-do comments</a></h3>
|
|
<p>Checks for comments that contain a specified regular expression. The default is <span class="default">"TODO:"</span>.</p>
|
|
|
|
<h3>Format of variable names</h3>
|
|
<p>Verifies that the format of the variable names conform to a specified regular expression. The formats can be overridden. The following table outlines the defaults:</p>
|
|
<a name="varformat"></a><table border="1" summary="variable format">
|
|
<tr class="header">
|
|
<td>Scope</td>
|
|
<td>Default Format</td>
|
|
<td>Example</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Constants (<span class="code">static</span> and <span class="code">final</span>)</td>
|
|
<td><span class="code">^[A-Z](_?[A-Z0-9]+)*$</span><br>The exception to the rule is for <span class="code">serialVersionUID</span>.</td>
|
|
<td><span class="code">public static final int MAX_ROWS = 2;</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Static variables (<span class="code">static</span> only)</td>
|
|
<td><span class="code">^[a-z][a-zA-Z0-9]*$</span></td>
|
|
<td><span class="code">private static int numCreated = 0;</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Members (non <span class="code">static</span>)</td>
|
|
<td><span class="code">^[a-z][a-zA-Z0-9]*$</span></td>
|
|
<td><span class="code">private int mySize = 0;</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Public members (non <span class="code">static public</span>)</td>
|
|
<td><span class="code">^f[A-Z][a-zA-Z0-9]*$</span></td>
|
|
<td><span class="code">public int fCMPField;</span></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The default values prior to release 1.4 were:</p>
|
|
<table border="1" summary="old values">
|
|
<tr class="header">
|
|
<td>Scope</td>
|
|
<td>Old Format</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code">static</span> only</td>
|
|
<td><span class="code">^s[A-Z][a-zA-Z0-9]*$</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>non <span class="code">static</span></td>
|
|
<td><span class="code">^m[A-Z][a-zA-Z0-9]*$</span></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3><a name="paramformat">Format of parameter names</a></h3>
|
|
<p>Verifies that the format of parameter names conform to a specified regular expression. The default is <span class="code">^[a-z][a-zA-Z0-9]*$</span>. The default value prior to release 1.4 was <span class="code">^a[A-Z][a-zA-Z0-9]*$</span>.</p>
|
|
|
|
|
|
<h3><a name="typeformat">Format of type names</a></h3>
|
|
<p>Verifies that the format of class and interface names conform to a specified regular expression. The default is <span class="code">^[A-Z][a-zA-Z0-9]*$</span>.</p>
|
|
|
|
|
|
<h3><a name="fieldformat">Format of public member names</a></h3>
|
|
<p>Verifies that the format of public member names conform to a specified regular expression. The default is <span class="code">^f[A-Z][a-zA-Z0-9]*$</span>. This is useful for the fields required for Container Managed Persistence (CMP) Enterprise JavaBeans 1.1.</p>
|
|
|
|
|
|
<h3><a name="methodformat">Format of method names</a></h3>
|
|
<p>Verifies that the format of method names conform to a specified regular expression. The default is <span class="code">^[a-z][a-zA-Z0-9]*$</span>.</p>
|
|
|
|
|
|
<h3><a name="localvarformat">Format of local variable names</a></h3>
|
|
<p>Verifies that the format of local variables conform to a specified regular expression. The default is <span class="code">^[a-z][a-zA-Z0-9]*$</span>.</p>
|
|
|
|
|
|
<h3>Integer Literals</h3>
|
|
<p>Verifies that long integer literals use an uppercase <span class="code">L</span>. For example <span class="code">40L</span> instead of <span class="code">40l</span>. This is in accordance to the Java Language Specification, <a href="http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#48282">Section 3.10.1</a>. This check can be turned off.</p>
|
|
|
|
|
|
<h3>Modifiers</h3>
|
|
<p>Checks that the order of modifiers conforms to the suggestions in the <a href="http://java.sun.com/docs/books/jls/second_edition/html/classes.doc.html">Java Language specification, sections 8.1.1, 8.3.1 and 8.4.3</a>. The correct order is <span class="code">public protected private abstract static final transient volatile synchronized native strictfp</span>.</p>
|
|
|
|
<p>Checks that method declarations in interfaces do not include the <span class="code">public</span> or <span class="code">abstract</span> modifiers, see the <a href="http://java.sun.com/docs/books/jls/second_edition/html/interfaces.doc.html">Java Language specification, section 9.4</a>.</p>
|
|
|
|
<h3>Visibility Modifiers</h3>
|
|
<p>Checks for data members that are not declared <span class="code">private</span>. Also finds <span class="code">static</span> non-<span class="code">final</span> data members that are not declared as <code>private</code>.</p>
|
|
|
|
<p>Note: you can turn on allowing <span class="code">protected</span> or <span class="code">package</span> visible data members.</p>
|
|
|
|
<div class="tip">
|
|
<h4 class="tip">Tip</h4>
|
|
<p>Container Managed Persistence EJBs require (in the EJB 1.1 specification) that managed fields are declared <span class="code">public</span>. This will cause checkstyle to complain that the fields should be declared <span class="code">private</span>. Hence checkstyle supports ignoring <span class="code">public</span> that match a specified regular expression. The default is <span class="code">^f[A-Z][a-zA-Z0-9]*$</span>.</p>
|
|
</div>
|
|
|
|
<h3>White space</h3>
|
|
<p>Checks for the following use of white space:</p>
|
|
<ul>
|
|
<li>Binary operators are separated from operands by spaces. For example <span class="code">x = y + 1;</span></li>
|
|
<li>Unary operators are not separated by spaces. For example <span class="code">x = --y + z++;</span></li>
|
|
<li>The keywords <span class="code">if/for/while/do/catch/synchronized/return</span> are surrounded by spaces.</li>
|
|
<li>Casts and commas (',') are followed by whitespace.</li>
|
|
<li>Periods ('.') are not surrounded by whitespace.</li>
|
|
<li>Correct padding of parenthesises <span class="code">()</span>'s.</li>
|
|
</ul>
|
|
|
|
<p>This feature can be turned off.</p>
|
|
|
|
<p>The options for specifying how to pad parenthesises are:</p>
|
|
<a name="parenpad"></a>
|
|
<table border="1" summary="parenthesises padding options">
|
|
<tr class="header">
|
|
<td>Option</td>
|
|
<td>Definition</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code">ignore</span></td>
|
|
<td>Ignore the padding.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code">nospace</span></td>
|
|
<td>Do not pad. For example, <span class="code">method(a, b);</span></td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<h3>Line wrapping on operators</h3>
|
|
<p>Checks for wrapping lines before operators. Examples of legal and illegal wrapping are:</p>
|
|
|
|
<pre>
|
|
// Valid
|
|
someVariable = aBigVariableNameToMakeThings + "this may work"
|
|
+ lookVeryInteresting;
|
|
// Invalid
|
|
anotherVariable = anotherBigVariableNameToMakeThings + "this may work" +
|
|
lookVeryInteresting;
|
|
</pre>
|
|
|
|
<p>This feature can be turned off.</p>
|
|
|
|
|
|
<h3>Missing Braces</h3>
|
|
<p>Checks for missing braces <span class="code">{}</span>'s for the following constructs:</p>
|
|
<ul>
|
|
<li><span class="code">if/else</span></li>
|
|
<li><span class="code">while</span></li>
|
|
<li><span class="code">for</span></li>
|
|
<li><span class="code">do/while</span></li>
|
|
</ul>
|
|
|
|
<p>This feature can be turned off.</p>
|
|
|
|
|
|
<h3><a name="File Header">File Header</a></h3>
|
|
<p>Ensure that the file starts with a specified header. The header contents are specified in a file. If no file is specified, checkstyle does not check for a header.</p>
|
|
|
|
<div class="tip">
|
|
<h4 class="tip">Tip</h4>
|
|
<p>Most copyright headers will contain date information (for example the year) which will change over time. To support this, checkstyle supports specifying the lines in the header to ignore when comparing the start of the file with the header. For example, consider the following header:</p>
|
|
|
|
<pre>
|
|
line 1: ///////////////////////////////////////////////////////////////////////
|
|
line 2: // checkstyle: Checks Java source code for adherence to a set of rules.
|
|
line 3: // Copyright (C) 2001 Oliver Burn
|
|
line 4: ///////////////////////////////////////////////////////////////////////
|
|
</pre>
|
|
|
|
<p>Since the year information will change over time, you can tell checkstyle to ignore line 3.</p>
|
|
</div>
|
|
|
|
<br>
|
|
<div class="tip">
|
|
<h4 class="tip">Tip</h4>
|
|
<p>Checkstyle also supports interpreting each header line as a regular expression. For example, consider the following header when regular expression checking is turned on:</p>
|
|
|
|
<pre>
|
|
line 1: /{71}
|
|
line 2: // checkstyle: Checks Java source code for adherence to a set of rules\.
|
|
line 3: // Copyright \(C\) \d\d\d\d Oliver Burn
|
|
line 4: // Last modification by \$Author.*\$
|
|
line 5: /{71}
|
|
</pre>
|
|
|
|
<p>Lines 1 and 5 demonstrate a more compact notation for 71 '/' characters. Line 3 enforces that the copyright notice includes a four digit year. Line 4 is an example how to enforce revision control keywords in a file header.</p>
|
|
</div>
|
|
|
|
<h3>Empty Blocks</h3>
|
|
<p>Checks for empty <span class="code">try</span>, <span class="code">catch</span>, <span class="code">finally</span> blocks. The checks can be configured with the following options:</p>
|
|
|
|
<a name="blockOpt"></a>
|
|
<table border="1" summary="block options">
|
|
<tr class="header">
|
|
<td>Option</td>
|
|
<td>Definition</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code">ignore</span></td>
|
|
<td>Ignore empty blocks.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code">text</span></td>
|
|
<td>Require that there is some text in the block. For example:
|
|
<pre>
|
|
catch (Exception ex) {
|
|
// This is a bad coding practice
|
|
}
|
|
</pre>
|
|
This is the default value.
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code">stmt</span></td>
|
|
<td>Require that there is a statement in the block. For example:
|
|
<pre>
|
|
finally {
|
|
lock.release();
|
|
}
|
|
</pre>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3>Instantiations</h3>
|
|
<p>Checks for instantiation of classes that should not be constructed directly. The list of these classes is configurable, the default is that no instantiations are illegal.</p>
|
|
<div class="tip">
|
|
<h4 class="tip">Tip</h4>
|
|
<p>A common mistake is to create new instances of <span class="code">java.lang.Boolean</span> instead of using the constants <span class="code">TRUE</span> and <span class="code">FALSE</span> or the <span class="code">Boolean.valueOf()</span> factory methods. This increases the program's memory requirements and wastes CPU cycles during memory allocation and garbage collection.</p>
|
|
<p>To find this error automatically, include <span class="code">java.lang.Boolean</span> in the list of illegal instantiations.</p>
|
|
</div>
|
|
|
|
<!-- formatters -->
|
|
<h2>Output Format</h2>
|
|
<p>The Checkstyle engine has a flexible output mechanism inspired by ANT. <a href="api/com/puppycrawl/tools/checkstyle/AuditEvent.html">AuditEvent</a> objects are generated (for found errors) and are consumed by listeners that implement the <a href="api/com/puppycrawl/tools/checkstyle/AuditListener.html">AuditListener</a> interface. The standard distribution comes with the following listeners:</p>
|
|
|
|
<ul>
|
|
<li><a href="api/com/puppycrawl/tools/checkstyle/DefaultLogger.html">DefaultLogger</a> - outputs the events in Emacs format. This is the one used by default (no surprise there:-).</li>
|
|
<li><a href="api/com/puppycrawl/tools/checkstyle/XMLLogger.html">XMLLogger</a> - outputs the messages in an XML format. This is ideal for generating pretty reports, or if you want to parse the output of Checkstyle.</li>
|
|
</ul>
|
|
|
|
<div class="tip">
|
|
<h4 class="tip">Tip</h4>
|
|
<p>It is possible to specify a base directory which files are then reported relative to. For example, if a base directory is specified as <span class="code">c:\projects\checkstyle</span>, then an error in the file <span class="code">c:\projects\checkstyle\src\dir\subdir\File.java</span> will be reported as <span class="code">src\dir\subdir\File.java</span>.</p>
|
|
</div>
|
|
|
|
<hr>
|
|
<p align="center">Copyright © 2001 Oliver Burn. All rights Reserved.</p>
|
|
</body>
|
|
</html>
|