<?xml version="1.0" encoding="ISO-8859-1"?>

<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>&#39;m&#39;</code>, followed
        by an upper case letter, and then letters and digits:
      </p>

      <source>
&lt;module name=&quot;MemberName&quot;&gt;
  &lt;property name=&quot;format&quot; value=&quot;^m[A-Z][a-zA-Z0-9]*$&quot;/&gt;
&lt;/module&gt;
      </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>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 and interfaces</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>
&lt;module name=&quot;LocalVariableName&quot;&gt;
    &lt;property name=&quot;format&quot; value=&quot;^e[a-zA-Z0-9]*$&quot;/&gt;
    &lt;property name=&quot;tokens&quot; value=&quot;PARAMETER_DEF&quot;/&gt;
&lt;/module&gt;
        </source>
      </subsection>

      <subsection name="TypeName">
        <p>
          Module <code>TypeName</code> also has property
          <code>tokens</code> which can be used to control whether the
          check applies to classes or interfaces through tokens
          <code>CLASS_DEF</code> and <code>INTERFACE_DEF</code>.  For
          example, the following configuration element ensures that
          interface names begin with <code>"I_"</code>, followed by
          letters and digits:
        </p>

        <source>
&lt;module name=&quot;TypeName&quot;&gt;
    &lt;property name=&quot;format&quot;
              value=&quot;^I_[a-zA-Z0-9]*$&quot;/&gt;
    &lt;property name=&quot;tokens&quot;
              value=&quot;INTERFACE_DEF&quot;/&gt;
&lt;/module&gt;
        </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>
&lt;module name=&quot;AbstractClassName&quot;&gt;
  &lt;property name=&quot;ignoreModifier&quot; value=&quot;true&quot;/&gt;
&lt;/module&gt;
        </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>
&lt;module name=&quot;PackageName&quot;&gt;
    &lt;property name=&quot;format&quot;
              value=&quot;^[a-z]+(\.[a-z][a-z0-9]*)*$&quot;/&gt;
&lt;/module&gt;
      </source>
    </section>
  </body>
</document>
