437 lines
15 KiB
XML
437 lines
15 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
|
<document xmlns="http://maven.apache.org/XDOC/2.0"
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|
xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
|
|
|
|
<properties>
|
|
<title>Naming Conventions</title>
|
|
<author>Checkstyle Development Team</author>
|
|
</properties>
|
|
|
|
<body>
|
|
|
|
<section name="Overview">
|
|
<p>
|
|
Each of these naming modules validates identifiers for particular code
|
|
elements. Valid identifiers for a naming module are specified by its
|
|
<code> format</code> property. The value of <code>format</code> is a <a
|
|
href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html">
|
|
regular expression</a> for valid identifiers. This is an example of a
|
|
configuration of the <code>MemberName</code> module to
|
|
ensure that member identifiers begin with
|
|
<code>'m'</code>, followed
|
|
by an upper case letter, and then letters and digits:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="MemberName">
|
|
<property name="format" value="^m[A-Z][a-zA-Z0-9]*$"/>
|
|
</module>
|
|
</source>
|
|
|
|
<p>
|
|
All naming modules belong to package <code>com.puppycrawl.tools.checkstyle.checks.naming</code> and
|
|
are submodules of <a href="config.html#TreeWalker"><code>TreeWalker</code></a>.
|
|
</p>
|
|
</section>
|
|
|
|
<section name="Modules">
|
|
<table>
|
|
<tr>
|
|
<th>module</th>
|
|
<th>validates identifiers for</th>
|
|
<th>default value of <code>format</code></th>
|
|
</tr>
|
|
<tr>
|
|
<td><code>AbstractClassName</code></td>
|
|
<td><code>abstract</code> classes</td>
|
|
<td><code>^Abstract.+$|^.*Factory$</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>ClassTypeParameterName</code></td>
|
|
<td>class type parameters</td>
|
|
<td><code>^[A-Z]$</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>ConstantName</code></td>
|
|
<td>
|
|
constants (<code>static</code>, <code>
|
|
final</code> fields)
|
|
</td>
|
|
<td><code>^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>LocalFinalVariableName</code></td>
|
|
<td>local, <code>final</code> variables, including
|
|
<code>catch</code> parameters</td>
|
|
<td><code>^[a-z][a-zA-Z0-9]*$</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>LocalVariableName</code></td>
|
|
<td>
|
|
local, non-<code>final</code> variables, including
|
|
<code>catch</code> parameters
|
|
</td>
|
|
<td><code>^[a-z][a-zA-Z0-9]*$</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>MemberName</code></td>
|
|
<td>non-<code>static</code> fields</td>
|
|
<td><code>^[a-z][a-zA-Z0-9]*$</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>MethodName</code></td>
|
|
<td>methods</td>
|
|
<td><code>^[a-z][a-zA-Z0-9]*$</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>MethodTypeParameterName</code></td>
|
|
<td>method type parameters</td>
|
|
<td><code>^[A-Z]$</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>InterfaceTypeParameterName</code></td>
|
|
<td>interface type parameters</td>
|
|
<td><code>^[A-Z]$</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>PackageName</code></td>
|
|
<td>packages</td>
|
|
<td>
|
|
<code>^[a-z]+(\.[a-zA-Z_][a-zA-Z0-9_]*)*$</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>ParameterName</code></td>
|
|
<td>parameters</td>
|
|
<td><code>^[a-z][a-zA-Z0-9]*$</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>StaticVariableName</code></td>
|
|
<td>
|
|
<code>static</code>, non-<code>final</code> fields
|
|
</td>
|
|
<td><code>^[a-z][a-zA-Z0-9]*$</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>TypeName</code></td>
|
|
<td>classes, interfaces, enums, and annotations</td>
|
|
<td><code>^[A-Z][a-zA-Z0-9]*$</code></td>
|
|
</tr>
|
|
</table>
|
|
</section>
|
|
|
|
<section name="Enhancements">
|
|
<subsection name="LocalVariableName">
|
|
<p>
|
|
Module <code>LocalVariableName</code> also has property
|
|
<code>tokens</code> which can be used to control whether the
|
|
check applies to variable declarations or <code>catch</code>
|
|
clause parameters through tokens <code>VARIABLE_DEF</code> and
|
|
<code>PARAMETER_DEF</code>. For example, the following
|
|
configuration element ensures that <code>catch</code> clause
|
|
parameters begin with <code>"e"</code>, followed by letters
|
|
and digits:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="LocalVariableName">
|
|
<property name="format" value="^e[a-zA-Z0-9]*$"/>
|
|
<property name="tokens" value="PARAMETER_DEF"/>
|
|
</module>
|
|
</source>
|
|
<p>
|
|
The check provides the following properties:
|
|
</p>
|
|
</subsection>
|
|
|
|
<table>
|
|
<tr>
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>allowOneCharVarInForLoop</td>
|
|
<td>
|
|
Allow one character variable name in <a href="http://docs.oracle.com/javase/tutorial/java/nutsandbolts/for.html"> initialization expressions</a> in FOR loop. For example:
|
|
<pre>
|
|
for (int i = 1; i < 10; i++) {}
|
|
</pre>
|
|
</td>
|
|
<td><a href="property_types.html#boolean">Boolean</a></td>
|
|
<td><code>false</code></td>
|
|
</tr>
|
|
</table>
|
|
<p>
|
|
An example of how to configure the check to allow one character variable name in
|
|
<a href="http://docs.oracle.com/javase/tutorial/java/nutsandbolts/for.html">
|
|
initialization expressions</a> in FOR loop:
|
|
</p>
|
|
<source>
|
|
<module name="LocalVariableName">
|
|
<property name="allowOneCharVarInForLoop" value="true"/>
|
|
</module>
|
|
</source>
|
|
<subsection name="TypeName">
|
|
<p>
|
|
Module <code>TypeName</code> also has property
|
|
<code>tokens</code>, which can be used to control the kind of type
|
|
that the check applies to. The value of the <code>tokens</code>
|
|
property is a comma-separated list of one or more of the following
|
|
tokens: <code>CLASS_DEF</code>, <code>INTERFACE_DEF</code>,
|
|
<code>ENUM_DEF</code>, <code>ANNOTATION_DEF</code>.<br/>
|
|
For example, the following configuration element ensures that
|
|
interface names begin with <code>"I_"</code>, followed by
|
|
letters and digits:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="TypeName">
|
|
<property name="format"
|
|
value="^I_[a-zA-Z0-9]*$"/>
|
|
<property name="tokens"
|
|
value="INTERFACE_DEF"/>
|
|
</module>
|
|
</source>
|
|
</subsection>
|
|
|
|
<subsection name="MethodName">
|
|
<p>
|
|
Module <code>MethodName</code> also has the following
|
|
properties:
|
|
</p>
|
|
|
|
<table>
|
|
<tr>
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>allowClassName</td>
|
|
<td>
|
|
Controls whether to allow a method name to have the same
|
|
name as the residing class name. This is not to be confused
|
|
with a constructor. An easy mistake is to place a return
|
|
type on a constructor declaration which turns it into a
|
|
method. For example:
|
|
<pre>
|
|
class MyClass {
|
|
public void MyClass() {} //this is a method
|
|
public MyClass() {} //this is a constructor
|
|
}
|
|
</pre>
|
|
</td>
|
|
<td><a href="property_types.html#boolean">Boolean</a></td>
|
|
<td><code>false</code></td>
|
|
</tr>
|
|
</table>
|
|
</subsection>
|
|
|
|
<subsection name="AbstractClassName">
|
|
<p>
|
|
Module <code>AbstractClassName</code> also has the following
|
|
properties:
|
|
</p>
|
|
|
|
<table>
|
|
<tr>
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>ignoreModifier</td>
|
|
<td>
|
|
Controls whether to ignore checking for the
|
|
<code>abstract</code> modifier on classes that match the
|
|
name.
|
|
</td>
|
|
<td><a href="property_types.html#boolean">Boolean</a></td>
|
|
<td><code>false</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>ignoreName</td>
|
|
<td>
|
|
Controls whether to ignore checking the name. Realistically
|
|
only useful if using the check to identify that match name
|
|
and do not have the <code>abstract</code> modifier. name.
|
|
</td>
|
|
<td><a href="property_types.html#boolean">Boolean</a></td>
|
|
<td><code>false</code></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>
|
|
The following example shows how to configure the
|
|
<code>AbstractClassName</code> to checks names, but ignore
|
|
missing <code>abstract</code> modifiers:
|
|
</p>
|
|
<source>
|
|
<module name="AbstractClassName">
|
|
<property name="ignoreModifier" value="true"/>
|
|
</module>
|
|
</source>
|
|
</subsection>
|
|
|
|
<subsection name="...">
|
|
<p>
|
|
The modules <code>ConstantName</code>,
|
|
<code>MemberName</code>, <code>StaticVariableName</code> and
|
|
<code>TypeName</code> also have the following properties:
|
|
</p>
|
|
|
|
<table>
|
|
<tr>
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>applyToPublic</td>
|
|
<td>Controls whether to apply the check to public member.</td>
|
|
<td><a href="property_types.html#boolean">Boolean</a></td>
|
|
<td><code>true</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>applyToProtected</td>
|
|
<td>Controls whether to apply the check to protected member.</td>
|
|
<td><a href="property_types.html#boolean">Boolean</a></td>
|
|
<td><code>true</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>applyToPackage</td>
|
|
<td>
|
|
Controls whether to apply the check to package-private member.
|
|
</td>
|
|
<td><a href="property_types.html#boolean">Boolean</a></td>
|
|
<td><code>true</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>applyToPrivate</td>
|
|
<td>Controls whether to apply the check to private member.</td>
|
|
<td><a href="property_types.html#boolean">Boolean</a></td>
|
|
<td><code>true</code></td>
|
|
</tr>
|
|
</table>
|
|
</subsection>
|
|
</section>
|
|
|
|
<section name="Notes">
|
|
<p>
|
|
The default value of <code>format</code> for module <code>PackageName</code> has been chosen to match the
|
|
requirements in the <a
|
|
href="http://java.sun.com/docs/books/jls/second_edition/html/packages.doc.html#40169">Java
|
|
Language specification</a> and the Sun coding conventions. However
|
|
both underscores and uppercase letters are rather uncommon, so most
|
|
configurations should probably assign value <code>^[a-z]+(\.[a-z][a-z0-9]*)*$</code> to <code>format</code> for module <code>PackageName</code>, as in
|
|
</p>
|
|
|
|
<source>
|
|
<module name="PackageName">
|
|
<property name="format"
|
|
value="^[a-z]+(\.[a-z][a-z0-9]*)*$"/>
|
|
</module>
|
|
</source>
|
|
</section>
|
|
|
|
<section name="AbbreviationAsWordInName">
|
|
<subsection name="Description">
|
|
<p>
|
|
The Check validate abbreviations(consecutive capital letters)
|
|
length in identifier name, it also allows to enforce camel case naming. Please read more at
|
|
<a href="http://google-styleguide.googlecode.com/svn/trunk/javaguide.html#s5.3-camel-case">
|
|
Google Style Guide</a>
|
|
to get to know how to avoid long abbreviations in names.
|
|
</p>
|
|
</subsection>
|
|
|
|
<subsection name="Properties">
|
|
<table>
|
|
<tr>
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>allowedAbbreviationLength</td>
|
|
<td> indicates on the allowed amount of capital letters in targeted identifiers
|
|
(abbreviations in the classes, interfaces, variables and methods names, ... ).</td>
|
|
<td><a href="property_types.html#integer">3</a></td>
|
|
<td>true</td>
|
|
</tr>
|
|
<tr>
|
|
<td>allowedAbbreviations</td>
|
|
<td>list of abbreviations that must be skipped for checking.
|
|
Abbreviations should be separated by comma, no spaces are allowed.</td>
|
|
<td><a href="property_types.html#stringSet">stringSet</a></td>
|
|
<td>null</td>
|
|
</tr>
|
|
<tr>
|
|
<td>ignoreFinal</td>
|
|
<td>allow to skip variables with final modifier.</td>
|
|
<td><a href="property_types.html#boolean">Boolean</a></td>
|
|
<td>true</td>
|
|
</tr>
|
|
<tr>
|
|
<td>ignoreStatic</td>
|
|
<td>allow to skip variables with static modifier.</td>
|
|
<td><a href="property_types.html#boolean">Boolean</a></td>
|
|
<td>true</td>
|
|
</tr>
|
|
<tr>
|
|
<td>ignoreOverriddenMethod</td>
|
|
<td>Allows to ignore methods tagged with @Override annotation
|
|
(that usually mean inherited name).</td>
|
|
<td><a href="property_types.html#boolean">Boolean</a></td>
|
|
<td>true</td>
|
|
</tr>
|
|
</table>
|
|
</subsection>
|
|
|
|
<subsection name="Examples">
|
|
<p>
|
|
Default configuration
|
|
<source>
|
|
<module name="AbbreviationAsWordInName"/>
|
|
</source>
|
|
</p>
|
|
<p>
|
|
To configure to check variables and classes identifiers,
|
|
do not ignore variables with static modifier and allow
|
|
no abbreviations (enforce camel case phrase) and
|
|
allow no abbreviations to use (camel case phrase) and allow XML and URL abbreviations.
|
|
</p>
|
|
<source>
|
|
<module name="AbbreviationAsWordInName">
|
|
<property name="tokens" value="VARIABLE_DEF,CLASS_DEF"/>
|
|
<property name="ignoreStatic" value="false"/>
|
|
<property name="allowedAbbreviationLength" value="1"/>
|
|
<property name="allowedAbbreviation" value="XML,URL"/>
|
|
</module>
|
|
</source>
|
|
</subsection>
|
|
|
|
<subsection name="Package">
|
|
<p>
|
|
com.puppycrawl.tools.checkstyle.checks.naming
|
|
</p>
|
|
</subsection>
|
|
|
|
<subsection name="Parent Module">
|
|
<p>
|
|
<a href="config.html#TreeWalker">TreeWalker</a>
|
|
</p>
|
|
</subsection>
|
|
</section>
|
|
|
|
</body>
|
|
</document>
|