TouchInstinct
/
checkstyle
307
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
checkstyle/src/xdocs/config_blocks.xml

621 lines
21 KiB
XML
Raw Blame History

<?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>Block Checks</title>
<author>Checkstyle Development Team</author>
</properties>
<body>
<section name="EmptyBlock">
<subsection name="Description">
<p> Checks for empty blocks. </p>
</subsection>
<subsection name="Properties">
<table>
<tr>
<th>name</th>
<th>description</th>
<th>type</th>
<th>default value</th>
</tr>
<tr>
<td>option</td>
<td>policy on block contents</td>
<td><a href="property_types.html#block">block policy</a></td>
<td><code>stmt</code></td>
</tr>
<tr>
<td>tokens</td>
<td>blocks to check</td>
<td>
subset of tokens <a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_DO">LITERAL_DO</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_ELSE">LITERAL_ELSE</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_FINALLY">LITERAL_FINALLY</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_IF">LITERAL_IF</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_FOR">LITERAL_FOR</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_TRY">LITERAL_TRY</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_WHILE">LITERAL_WHILE</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INSTANCE_INIT">INSTANCE_INIT</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#STATIC_INIT">STATIC_INIT</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_SWITCH">LITERAL_SWITCH</a>.
</td>
<td>all tokens</td>
</tr>
</table>
</subsection>
<subsection name="Examples">
<p> To configure the check: </p>
<source>
&lt;module name=&quot;EmptyBlock&quot;/&gt;
</source>
<p>
To configure the check for the <code>text</code>
policy and only <code> try</code> blocks:
</p>
<source>
&lt;module name=&quot;EmptyBlock&quot;&gt;
&lt;property name=&quot;option&quot; value=&quot;text&quot;/&gt;
&lt;property name=&quot;tokens&quot; value=&quot;LITERAL_TRY&quot;/&gt;
&lt;/module&gt;
</source>
</subsection>
<subsection name="Package">
<p> com.puppycrawl.tools.checkstyle.checks.blocks </p>
</subsection>
<subsection name="Parent Module">
<p> <a href="config.html#TreeWalker">TreeWalker</a> </p>
</subsection>
</section>
<section name="EmptyCatchBlock">
<subsection name="Description">
<p>
Checks for empty catch blocks. There are two options to make validation more precise
(by default Check allows empty catch block with any comment inside):
</p>
</subsection>
<subsection name="Properties">
<table>
<tr>
<th>name</th>
<th>description</th>
<th>type</th>
<th>default value</th>
</tr>
<tr>
<td>exceptionVariableName</td>
<td>The name of variable associated with exception</td>
<td><a href="property_types.html#string">String</a></td>
<td>^$</td>
</tr>
<tr>
<td>commentFormat</td>
<td>The format of the first comment inside empty catch</td>
<td><a href="property_types.html#string">String</a></td>
<td>.*</td>
</tr>
</table>
</subsection>
<subsection name="Examples">
<p>
To configure the Check to suppress empty catch block if exception's variable name is
<code>expected</code> or <code>ignore</code> or there's any comment inside:
</p>
<source>
&lt;module name=&quot;EmptyCatchBlock&quot;&gt;
&lt;property name=&quot;exceptionVariableName&quot; value=&quot;expected|ignore&quot;/&gt;
&lt;/module&gt;
</source>
<p>
To configure the Check to suppress empty catch block if single-line comment inside
is &quot;//This is expected&quot;:
</p>
<source>
&lt;module name=&quot;EmptyCatchBlock&quot;&gt;
&lt;property name=&quot;commentFormat&quot; value=&quot;This is expected&quot;/&gt;
&lt;/module&gt;
</source>
<p>
To configure the Check to suppress empty catch block if single-line comment inside
is &quot;//This is expected&quot; or exception's
variable name is &quot;myException&quot; (any option is matching):
</p>
<source>
&lt;module name=&quot;EmptyCatchBlock&quot;&gt;
&lt;property name=&quot;commentFormat&quot; value=&quot;This is expected&quot;/&gt;
&lt;property name=&quot;exceptionVariableName&quot; value=&quot;myException&quot;/&gt;
&lt;/module&gt;
</source>
<p>
Such empty blocks would be suppressed:
</p>
<source>
try {
throw new RuntimeException();
} catch (RuntimeException e) {
//This is expected
}
...
try {
throw new RuntimeException();
} catch (RuntimeException e) {
// This is expected
}
...
try {
throw new RuntimeException();
} catch (RuntimeException e) {
// This is expected
// some another comment
}
...
try {
throw new RuntimeException();
} catch (RuntimeException e) {
/* This is expected */
}
...
try {
throw new RuntimeException();
} catch (RuntimeException e) {
/*
*
* This is expected
* some another comment
*/
}
...
try {
throw new RuntimeException();
} catch (RuntimeException myException) {
}
</source>
</subsection>
<subsection name="Package">
<p> com.puppycrawl.tools.checkstyle.checks.blocks </p>
</subsection>
<subsection name="Parent Module">
<p> <a href="config.html#TreeWalker">TreeWalker</a> </p>
</subsection>
</section>
<section name="LeftCurly">
<subsection name="Description">
<p>
Checks for the placement of left curly braces
(<code>'{'</code>) for code blocks. The policy to verify is
specified using the property <code>option</code>. Policies
<code>eol</code> and <code> nlow</code> take into account
the property <code>maxLineLength</code>.
</p>
</subsection>
<subsection name="Properties">
<table>
<tr>
<th>name</th>
<th>description</th>
<th>type</th>
<th>default value</th>
</tr>
<tr>
<td>option</td>
<td>policy on placement of a left curly brace (<code>'{'</code>)</td>
<td><a href="property_types.html#lcurly">left curly brace policy</a></td>
<td><code>eol</code></td>
</tr>
<tr>
<td>ignoreEnums</td>
<td>If true, Check will ignore enums</td>
<td><a href="property_types.html#boolean">boolean</a></td>
<td>true</td>
</tr>
<tr>
<td>maxLineLength</td>
<td>maximum number of characters in a line</td>
<td><a href="property_types.html#integer">integer</a></td>
<td><code>80</code></td>
</tr>
<tr>
<td>tokens</td>
<td>blocks to check</td>
<td>subset of tokens
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_DEF">ANNOTATION_DEF</a>,
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF">CLASS_DEF</a>,
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF">CTOR_DEF</a>,
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_DEF">ENUM_DEF</a>,
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_CONSTANT_DEF">ENUM_CONSTANT_DEF</a>,
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF">INTERFACE_DEF</a>,
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_CATCH">LITERAL_CATCH</a>,
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_DO">LITERAL_DO</a>,
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_ELSE">LITERAL_ELSE</a>,
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_FINALLY">LITERAL_FINALLY</a>,
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_FOR">LITERAL_FOR</a>,
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_IF">LITERAL_IF</a>,
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_SWITCH">LITERAL_SWITCH</a>,
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_SYNCHRONIZED">LITERAL_SYNCHRONIZED</a>,
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_TRY">LITERAL_TRY</a>,
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_WHILE">LITERAL_WHILE</a>,
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF">METHOD_DEF</a>
</td>
<td>all tokens</td>
</tr>
</table>
</subsection>
<subsection name="Examples">
<p> To configure the check: </p>
<source>
&lt;module name=&quot;LeftCurly&quot;/&gt;
</source>
<p>
To configure the check to apply the <code>nl</code> policy to
type blocks:
</p>
<source>
&lt;module name=&quot;LeftCurly&quot;&gt;
&lt;property name=&quot;option&quot; value=&quot;nl&quot;/&gt;
&lt;property name=&quot;tokens&quot; value=&quot;CLASS_DEF,INTERFACE_DEF&quot;/&gt;
&lt;/module&gt;
</source>
<p>
An example of how to configure the check to validate enum definitions:
</p>
<source>
&lt;module name="LeftCurly"&gt;
&lt;property name="ignoreEnums" value="false"/&gt;
&lt;/module&gt;
</source>
</subsection>
<subsection name="Package">
<p> com.puppycrawl.tools.checkstyle.checks.blocks </p>
</subsection>
<subsection name="Parent Module">
<p> <a href="config.html#TreeWalker">TreeWalker</a> </p>
</subsection>
</section>
<section name="NeedBraces">
<subsection name="Description">
<p> Checks for braces around code blocks. </p>
</subsection>
<subsection name="Properties">
<table>
<tr>
<th>name</th>
<th>description</th>
<th>type</th>
<th>default value</th>
</tr>
<tr>
<td>tokens</td>
<td>blocks to check</td>
<td>subset of tokens <a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_DO">LITERAL_DO</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_ELSE">LITERAL_ELSE</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_IF">LITERAL_IF</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_FOR">LITERAL_FOR</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_WHILE">LITERAL_WHILE</a></td>
<td>all tokens</td>
</tr>
<tr>
<td>allowSingleLineStatement</td>
<td>allows single-line statements without braces</td>
<td><a href="property_types.html#boolean">boolean</a></td>
<td>false</td>
</tr>
</table>
</subsection>
<subsection name="Examples">
<p> To configure the check: </p>
<source>
&lt;module name=&quot;NeedBraces&quot;/&gt;
</source>
<p>
To configure the check for <code>if</code> and
<code> else</code> blocks:
</p>
<source>
&lt;module name=&quot;NeedBraces&quot;&gt;
&lt;property name=&quot;tokens&quot; value=&quot;LITERAL_IF, LITERAL_ELSE&quot;/&gt;
&lt;/module&gt;
</source>
<p>
To configure the check to allow single-line statements
(<code>if, while, do-while, for</code>) without braces:
</p>
<source>
&lt;module name=&quot;NeedBraces&quot;&gt;
&lt;property name=&quot;allowSingleLineStatement&quot; value=&quot;true&quot;/&gt;
&lt;/module&gt;
</source>
<p>
Next statements won't be violated by Check:
</p>
<source>
if (obj.isValid()) return true; // OK
while (obj.isValid()) return true; // OK
do this.notify(); while (o != null); // OK
for (int i = 0; ; ) this.notify(); // OK
</source>
<p>
To configure the Check to allow <code>case, default</code> single-line statements
without braces:
</p>
<source>
&lt;module name=&quot;NeedBraces&quot;&gt;
&lt;property name=&quot;tokens&quot; value=&quot;LITERAL_CASE, LITERAL_DEFAULT&quot;/&gt;
&lt;property name=&quot;allowSingleLineStatement&quot; value=&quot;true&quot;/&gt;
&lt;/module&gt;
</source>
<p>
Next statements won't be violated by Check:
</p>
<source>
switch (num) {
case 1: counter++; break; // OK
case 6: counter += 10; break; // OK
default: counter = 100; break; // OK
}
</source>
</subsection>
<subsection name="Package">
<p> com.puppycrawl.tools.checkstyle.checks.blocks </p>
</subsection>
<subsection name="Parent Module">
<p> <a href="config.html#TreeWalker">TreeWalker</a> </p>
</subsection>
</section>
<section name="RightCurly">
<subsection name="Description">
<p>
Checks the placement of right curly braces (<code>'}'</code>)
for <code> else</code>, <code>try</code>, and
<code>catch</code> tokens. The policy to verify is specified
using the property <code> option</code>.
</p>
</subsection>
<subsection name="Properties">
<table>
<tr>
<th>name</th>
<th>description</th>
<th>type</th>
<th>default value</th>
</tr>
<tr>
<td>option</td>
<td>policy on placement of a right curly brace (<code>'}'</code>)</td>
<td><a href="property_types.html#rcurly">right curly brace policy</a></td>
<td><code>same</code></td>
</tr>
<tr>
<td>tokens</td>
<td>blocks to check</td>
<td>subset of tokens <a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_TRY">LITERAL_TRY</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_CATCH">LITERAL_CATCH</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_FINALLY">LITERAL_FINALLY</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_IF">LITERAL_IF</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_ELSE">LITERAL_ELSE</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF">CLASS_DEF</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF">METHOD_DEF</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF">CTOR_DEF</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_FOR">LITERAL_FOR</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_WHILE">LITERAL_WHILE</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_DO">LITERAL_DO</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#STATIC_INIT">STATIC_INIT</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INSTANCE_INIT">INSTANCE_INIT</a>.</td>
<td><a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_TRY">LITERAL_TRY</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_CATCH">LITERAL_CATCH</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_FINALLY">LITERAL_FINALLY</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_IF">LITERAL_IF</a>,
<a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_ELSE">LITERAL_ELSE</a></td>
</tr>
<tr>
<td>shouldStartLine</td>
<td>should we check if <code>'}'</code>
starts line.</td>
<td><a href="property_types.html#boolean">boolean</a></td>
<td><code>true</code></td>
</tr>
</table>
</subsection>
<subsection name="Examples">
<p> To configure the check: </p>
<source>
&lt;module name=&quot;RightCurly&quot;/&gt;
</source>
<p>
To configure the check with policy <code>alone</code> for <code> else</code> and <a
href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF">METHOD_DEF</a>
tokens:
</p>
<source>
&lt;module name=&quot;RightCurly&quot;&gt;
&lt;property name=&quot;option&quot; value=&quot;alone&quot;/&gt;
&lt;property name=&quot;tokens&quot; value=&quot;LITERAL_ELSE, METHOD_DEF&quot;/&gt;
&lt;/module&gt;
</source>
</subsection>
<subsection name="Package">
<p> com.puppycrawl.tools.checkstyle.checks.blocks </p>
</subsection>
<subsection name="Parent Module">
<p> <a href="config.html#TreeWalker">TreeWalker</a> </p>
</subsection>
</section>
<section name="AvoidNestedBlocks">
<subsection name="Description">
<p>
Finds nested blocks, i.e. blocks that are used freely in the code.
</p>
<p>
Rationale: Nested blocks are often leftovers from the
debugging process, they confuse the reader.
</p>
<p>
For example this Check finds the obsolete braces in
</p>
<source>
public void guessTheOutput()
{
int whichIsWhich = 0;
{
int whichIsWhich = 2;
}
System.out.println("value = " + whichIsWhich);
}
</source>
<p> and debugging / refactoring leftovers such as </p>
<source>
// if (conditionThatIsNotUsedAnyLonger)
{
System.out.println("unconditional");
}
</source>
<p>
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.
</p>
<source>
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;
}
}
</source>
</subsection>
<subsection name="Properties">
<table>
<tr>
<th>name</th>
<th>description</th>
<th>type</th>
<th>default value</th>
</tr>
<tr>
<td>allowInSwitchCase</td>
<td>Allow nested blocks in case statements</td>
<td><a href="property_types.html#boolean">boolean</a></td>
<td><code>false</code></td>
</tr>
</table>
</subsection>
<subsection name="Examples">
<p> To configure the check: </p>
<source>
&lt;module name=&quot;AvoidNestedBlocks&quot;/&gt;
</source>
</subsection>
<subsection name="Package">
<p> com.puppycrawl.tools.checkstyle.checks.blocks </p>
</subsection>
<subsection name="Parent Module">
<p> <a href="config.html#TreeWalker">TreeWalker</a> </p>
</subsection>
</section>
</body>
</document>
Reference in New Issue View Git Blame Copy Permalink