243 lines
12 KiB
HTML
243 lines
12 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
|
|
<html>
|
|
<head>
|
|
<title>Checkstyle Core Engine</title>
|
|
<link rel="stylesheet" type="text/css" href="mystyle.css">
|
|
</head>
|
|
|
|
<body>
|
|
<h1>Checkstyle Core Engine</h1>
|
|
|
|
<p>Author: <a href="mailto:checkstyle@puppycrawl.com">Oliver Burn</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.4beta3 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>
|
|
|
|
<h3><a name="imports">Imports</a></h3>
|
|
<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>
|
|
|
|
<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="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.</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 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 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>.
|
|
|
|
<h3>Tab characters</h3>
|
|
<p>Checks for lines that contain tab (<code>'\t'</code>) characters. This can be turned off.</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_]*[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>Visibility Modifiers</h3>
|
|
<p>Checks for data members that are not declared <code>private</code>. Also finds <code>static</code> non-<code>final</code> data members that are not declared as <code>private</code>.</p>
|
|
|
|
<p>Note: you can turn on allowing <code>protected</code> or package 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 white space.
|
|
</ul>
|
|
|
|
<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 a line 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>
|
|
|
|
|
|
<!-- 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>
|
|
|
|
|
|
<hr>
|
|
<p align="center">Copyright © 2001 Oliver Burn. All rights Reserved.</p>
|
|
</body>
|
|
</html>
|