| <?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"> |
| |
| <head> |
| <title>Miscellaneous</title> |
| <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"/> |
| <script type="text/javascript" src="js/anchors.js"/> |
| <script type="text/javascript" src="js/google-analytics.js"/> |
| <link rel="icon" href="images/favicon.png" type="image/x-icon" /> |
| <link rel="shortcut icon" href="images/favicon.ico" type="image/ico" /> |
| </head> |
| |
| <body> |
| <section name="Content"> |
| <macro name="toc"> |
| <param name="fromDepth" value="1"/> |
| <param name="toDepth" value="1"/> |
| </macro> |
| </section> |
| |
| <section name="ArrayTypeStyle"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.1</p> |
| <p> |
| Checks the style of array type definitions. Some like Java style: |
| <code>public static void main(String[] args)</code> and some like |
| C style: public static void main(String args[]) |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>javaStyle</td> |
| <td> |
| Controls whether to enforce Java style (true) or C style (false). |
| </td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>true</code></td> |
| <td>3.1</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the check to enforce Java style: |
| </p> |
| <source> |
| <module name="ArrayTypeStyle"/> |
| </source> |
| |
| <p> |
| To configure the check to enforce C style: |
| </p> |
| <source> |
| <module name="ArrayTypeStyle"> |
| <property name="javaStyle" value="false"/> |
| </module> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+ArrayTypeStyle"> |
| Google Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Asun_checks.xml+repo%3Acheckstyle%2Fcheckstyle+ArrayTypeStyle"> |
| Sun Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+ArrayTypeStyle"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22array.type.style%22"> |
| array.type.style</a> |
| </li> |
| </ul> |
| <p> |
| All messages can be customized if the default message doesn't suit you. |
| Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to. |
| </p> |
| </subsection> |
| |
| <subsection name="Package"> |
| <p> |
| com.puppycrawl.tools.checkstyle.checks |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="AvoidEscapedUnicodeCharacters"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 5.8</p> |
| <p> |
| Restrict using <a href = "https://docs.oracle.com/javase/specs/jls/se7/html/jls-3.html#jls-3.3"> |
| Unicode escapes</a> (e.g. \u221e). |
| It is possible to allow using escapes for |
| <a href="https://en.wiktionary.org/wiki/Appendix:Control_characters"> non-printable(control) characters</a>. |
| Also, this check can be configured to allow using escapes |
| if trail comment is present. By the option it is possible to |
| allow using escapes if literal contains only them. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>allowEscapesForControlCharacters</td> |
| <td>Allow use escapes for non-printable(control) characters.</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td>false</td> |
| <td>5.8</td> |
| </tr> |
| <tr> |
| <td>allowByTailComment</td> |
| <td>Allow use escapes if trail comment is present.</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td>false</td> |
| <td>5.8</td> |
| </tr> |
| <tr> |
| <td>allowIfAllCharactersEscaped</td> |
| <td>Allow if all characters in literal are escaped.</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td>false</td> |
| <td>5.8</td> |
| </tr> |
| <tr> |
| <td>allowNonPrintableEscapes</td> |
| <td>Allow non-printable escapes.</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td>false</td> |
| <td>5.8</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| Examples of using Unicode: |
| </p> |
| <source> |
| String unitAbbrev = "μs"; //Best: perfectly clear even without a comment. |
| String unitAbbrev = "\u03bcs"; //Poor: the reader has no idea what this is. |
| </source> |
| <p> |
| An example of how to configure the check is: |
| </p> |
| <source> |
| <module name="AvoidEscapedUnicodeCharacters"/> |
| </source> |
| <p> |
| An example of non-printable(control) characters. |
| </p> |
| <source> |
| return '\ufeff' + content; // byte order mark |
| </source> |
| <p> |
| An example of how to configure the check to allow using escapes |
| for non-printable(control) characters: |
| </p> |
| <source> |
| <module name="AvoidEscapedUnicodeCharacters"> |
| <property name="allowEscapesForControlCharacters" value="true"/> |
| </module> |
| </source> |
| <p> |
| Example of using escapes with trail comment: |
| </p> |
| <source> |
| String unitAbbrev = "\u03bcs"; // Greek letter mu, "s" |
| </source> |
| <p> |
| An example of how to configure the check to allow using escapes |
| if trail comment is present: |
| </p> |
| <source> |
| <module name="AvoidEscapedUnicodeCharacters"> |
| <property name="allowByTailComment" value="true"/> |
| </module> |
| </source> |
| <p> |
| Example of using escapes if literal contains only them: |
| </p> |
| <source> |
| String unitAbbrev = "\u03bc\u03bc\u03bc"; |
| </source> |
| <p> |
| An example of how to configure the check to allow escapes |
| if literal contains only them: |
| </p> |
| <source> |
| <module name="AvoidEscapedUnicodeCharacters"> |
| <property name="allowIfAllCharactersEscaped" value="true"/> |
| </module> |
| </source> |
| <p> |
| An example of how to configure the check to allow non-printable escapes: |
| </p> |
| <source> |
| <module name="AvoidEscapedUnicodeCharacters"> |
| <property name="allowNonPrintableEscapes" value="true"/> |
| </module> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+AvoidEscapedUnicodeCharacters"> |
| Google Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+AvoidEscapedUnicodeCharacters"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22forbid.escaped.unicode.char%22"> |
| forbid.escaped.unicode.char</a> |
| </li> |
| </ul> |
| <p> |
| All messages can be customized if the default message doesn't suit you. |
| Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to. |
| </p> |
| </subsection> |
| |
| <subsection name="Package"> |
| <p> |
| com.puppycrawl.tools.checkstyle.checks |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="CommentsIndentation"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 6.10</p> |
| <p> |
| Controls the indentation between comments and surrounding code. |
| Comments are indented at the same level as the surrounding code. |
| Detailed info about such convention can be found <a href= |
| "http://checkstyle.sourceforge.net/reports/google-java-style-20170228.html#s4.8.6.1-block-comment-style"> |
| here</a> |
| </p> |
| <p>Please take a look at the following examples to understand how the check works:</p> |
| |
| <p>Example #1: Block comments.</p> |
| <source> |
| 1 /* |
| 2 * it is Ok |
| 3 */ |
| 4 boolean bool = true; |
| 5 |
| 6 /* violation |
| 7 * (block comment should have the same indentation level as line 9) |
| 8 */ |
| 9 double d = 3.14; |
| </source> |
| <p>Example #2: Comment is placed at the end of the block and has previous statement.</p> |
| <source> |
| 1 public void foo1() { |
| 2 foo2(); |
| 3 // it is OK |
| 4 } |
| 5 |
| 6 public void foo2() { |
| 7 foo3(); |
| 8 // violation (comment should have the same indentation level as line 7) |
| 9 } |
| </source> |
| <p>Example #3: Comment is used as a single line border to separate groups of methods.</p> |
| <source> |
| 1 /////////////////////////////// it is OK |
| 2 |
| 3 public void foo7() { |
| 4 int a = 0; |
| 5 } |
| 6 |
| 7 /////////////////////////////// violation (should have the same indentation level as line 9) |
| 8 |
| 9 public void foo8() {} |
| </source> |
| <p>Example #4: Comment has distributed previous statement.</p> |
| <source> |
| 1 public void foo11() { |
| 2 CheckUtils |
| 3 .getFirstNode(new DetailAST()) |
| 4 .getFirstChild() |
| 5 .getNextSibling(); |
| 6 // it is OK |
| 7 } |
| 8 |
| 9 public void foo12() { |
| 10 CheckUtils |
| 11 .getFirstNode(new DetailAST()) |
| 12 .getFirstChild() |
| 13 .getNextSibling(); |
| 14 // violation (should have the same indentation level as line 10) |
| 15 } |
| </source> |
| <p> |
| Example #5: Single line block comment is placed within an empty code block. |
| Note, if comment is placed at the end of the empty code block, we have Checkstyle's |
| limitations to clearly detect user intention of explanation target - above or below. The |
| only case we can assume as a violation is when a single line comment within the empty |
| code block has indentation level that is lower than the indentation level of the closing |
| right curly brace. |
| </p> |
| <source> |
| 1 public void foo46() { |
| 2 // comment |
| 3 // block |
| 4 // it is OK (we cannot clearly detect user intention of explanation target) |
| 5 } |
| 6 |
| 7 public void foo46() { |
| 8 // comment |
| 9 // block |
| 10 // violation (comment hould have the same indentation level as line 11) |
| 11 } |
| </source> |
| <p>Example #6: 'fallthrough' comments and similar.</p> |
| <source> |
| 0 switch(a) { |
| 1 case "1": |
| 2 int k = 7; |
| 3 // it is OK |
| 4 case "2": |
| 5 int k = 7; |
| 6 // it is OK |
| 7 case "3": |
| 8 if (true) {} |
| 9 // violation (should have the same indentation level as line 8 or 10) |
| 10 case "4": |
| 11 case "5": { |
| 12 int a; |
| 13 } |
| 14 // fall through (it is OK) |
| 15 case "12": { |
| 16 int a; |
| 17 } |
| 18 default: |
| 19 // it is OK |
| 20 } |
| </source> |
| <p>Example #7: Comment is placed within a distributed statement.</p> |
| <source> |
| 1 String breaks = "J" |
| 2 // violation (comment should have the same indentation level as line 3) |
| 3 + "A" |
| 4 // it is OK |
| 5 + "V" |
| 6 + "A" |
| 7 // it is OK |
| 8 ; |
| </source> |
| <p> |
| Example #8: Comment is placed within an empty case block. |
| Note, if comment is placed at the end of the empty case block, we have Checkstyle's |
| limitations to clearly detect user intention of explanation target - above or below. The |
| only case we can assume as a violation is when a single line comment within the empty case |
| block has indentation level that is lower than the indentation level of the next case |
| token. |
| </p> |
| <source> |
| 1 case 4: |
| 2 // it is OK |
| 3 case 5: |
| 4 // violation (should have the same indentation level as line 3 or 5) |
| 5 case 6: |
| </source> |
| <p>Example #9: Single line block comment has previous and next statement.</p> |
| <source> |
| 1 String s1 = "Clean code!"; |
| 2 s.toString().toString().toString(); |
| 3 // single line |
| 4 // block |
| 5 // comment (it is OK) |
| 6 int a = 5; |
| 7 |
| 8 String s2 = "Code complete!"; |
| 9 s.toString().toString().toString(); |
| 10 // violation (should have the same indentation level as line 11) |
| 11 // violation (should have the same indentation level as line 12) |
| 12 // violation (should have the same indentation level as line 13) |
| 13 int b = 18; |
| </source> |
| <p>Example #10: Comment within the block tries to describe the next code block.</p> |
| <source> |
| 1 public void foo42() { |
| 2 int a = 5; |
| 3 if (a == 5) { |
| 4 int b; |
| 5 // it is OK |
| 6 } else if (a ==6) { ... } |
| 7 } |
| 8 |
| 9 public void foo43() { |
| 10 try { |
| 11 int a; |
| 12 // Why do we catch exception here? - violation (should have the same indentation as line 11) |
| 13 } catch (Exception e) { ... } |
| 14 } |
| </source> |
| </subsection> |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>tokens</td> |
| <td>tokens to check</td> |
| <td> |
| subset of tokens |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#SINGLE_LINE_COMMENT">SINGLE_LINE_COMMENT</a>, |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#BLOCK_COMMENT_BEGIN">BLOCK_COMMENT_BEGIN</a>. |
| </td> |
| <td> |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#SINGLE_LINE_COMMENT">SINGLE_LINE_COMMENT</a>, |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#BLOCK_COMMENT_BEGIN">BLOCK_COMMENT_BEGIN</a>. |
| </td> |
| <td>6.10</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the Check: |
| </p> |
| <source> |
| <module name="CommentsIndentation"/> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+CommentsIndentation"> |
| Google Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+CommentsIndentation"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Findentation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22comments.indentation.block%22"> |
| comments.indentation.block</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Findentation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22comments.indentation.single%22"> |
| comments.indentation.single</a> |
| </li> |
| </ul> |
| <p> |
| All messages can be customized if the default message doesn't suit you. |
| Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to. |
| </p> |
| </subsection> |
| |
| <subsection name="Package"> |
| <p> |
| com.puppycrawl.tools.checkstyle.checks.indentation |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="DescendantToken"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.2</p> |
| <p> |
| Checks for restricted tokens beneath other tokens. |
| </p> |
| |
| <p> |
| WARNING: This is a very powerful and flexible check, but, at the |
| same time, it is low-level and very implementation-dependent because |
| its results depend on the grammar we use to build abstract syntax |
| trees. Thus we recommend using other checks when they provide the |
| desired functionality. Essentially, this check just works on the level |
| of an abstract syntax tree and knows nothing about language structures. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>limitedTokens</td> |
| <td>set of tokens with limited occurrences as descendants</td> |
| <td> |
| subset of tokens |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html">TokenTypes</a> |
| </td> |
| <td>empty set</td> |
| <td>3.2</td> |
| </tr> |
| <tr> |
| <td>minimumDepth</td> |
| <td>the minimum depth for descendant counts</td> |
| <td><a href="property_types.html#integer">Integer</a></td> |
| <td>0</td> |
| <td>3.2</td> |
| </tr> |
| <tr> |
| <td>maximumDepth</td> |
| <td>the maximum depth for descendant counts</td> |
| <td><a href="property_types.html#integer">Integer</a></td> |
| <td>java.lang.Integer.MAX_VALUE</td> |
| <td>3.2</td> |
| </tr> |
| <tr> |
| <td>minimumNumber</td> |
| <td>a minimum count for descendants</td> |
| <td><a href="property_types.html#integer">Integer</a></td> |
| <td>0</td> |
| <td>3.2</td> |
| </tr> |
| <tr> |
| <td>maximumNumber</td> |
| <td>a maximum count for descendants</td> |
| <td><a href="property_types.html#integer">Integer</a></td> |
| <td>java.lang.Integer.MAX_VALUE</td> |
| <td>3.2</td> |
| </tr> |
| <tr> |
| <td>sumTokenCounts</td> |
| <td> |
| whether the number of tokens found should be calculated |
| from the sum of the individual token counts |
| </td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>false</code></td> |
| <td>5.0</td> |
| </tr> |
| <tr> |
| <td>minimumMessage</td> |
| <td>error message when the minimum count is not reached</td> |
| <td><a href="property_types.html#string">String</a></td> |
| <td>"descendant.token.min"</td> |
| <td>3.2</td> |
| </tr> |
| <tr> |
| <td>maximumMessage</td> |
| <td>error message when the maximum count is exceeded</td> |
| <td><a href="property_types.html#string">String</a></td> |
| <td>"descendant.token.max"</td> |
| <td>3.2</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| |
| <p>Switch with no default:</p> |
| <source> |
| <module name="DescendantToken"> |
| <property name="tokens" value="LITERAL_SWITCH"/> |
| <property name="maximumDepth" value="2"/> |
| <property name="limitedTokens" value="LITERAL_DEFAULT"/> |
| <property name="minimumNumber" value="1"/> |
| </module> |
| </source> |
| |
| <p> |
| The condition in <code>for</code> performs no check: |
| </p> |
| <source> |
| <module name="DescendantToken"> |
| <property name="tokens" value="FOR_CONDITION"/> |
| <property name="limitedTokens" value="EXPR"/> |
| <property name="minimumNumber" value="1"/> |
| </module> |
| </source> |
| |
| <p> |
| Comparing <code>this</code> with <code>null</code> (i.e. <code>this == |
| null</code> and <code>this != null</code>): |
| </p> |
| <source> |
| <module name="DescendantToken"> |
| <property name="tokens" value="EQUAL,NOT_EQUAL"/> |
| <property name="limitedTokens" value="LITERAL_THIS,LITERAL_NULL"/> |
| <property name="maximumNumber" value="1"/> |
| <property name="maximumDepth" value="1"/> |
| <property name="sumTokenCounts" value="true"/> |
| </module> |
| </source> |
| |
| <p>String literal equality check:</p> |
| <source> |
| <module name="DescendantToken"> |
| <property name="tokens" value="EQUAL,NOT_EQUAL"/> |
| <property name="limitedTokens" value="STRING_LITERAL"/> |
| <property name="maximumNumber" value="0"/> |
| <property name="maximumDepth" value="1"/> |
| </module> |
| </source> |
| |
| <p> |
| Assert statement may have side effects (formatted for browser |
| display): |
| </p> |
| <source> |
| <module name="DescendantToken"> |
| <property name="tokens" value="LITERAL_ASSERT"/> |
| <property name="limitedTokens" value="ASSIGN,DEC,INC,POST_DEC, |
| POST_INC,PLUS_ASSIGN,MINUS_ASSIGN,STAR_ASSIGN,DIV_ASSIGN,MOD_ASSIGN, |
| BSR_ASSIGN,SR_ASSIGN,SL_ASSIGN,BAND_ASSIGN,BXOR_ASSIGN,BOR_ASSIGN, |
| METHOD_CALL"/> |
| <property name="maximumNumber" value="0"/> |
| </module> |
| </source> |
| |
| <p> |
| The initialiser in <code>for</code> performs no setup (where a <code>while</code> statement could be used instead): |
| </p> |
| <source> |
| <module name="DescendantToken"> |
| <property name="tokens" value="FOR_INIT"/> |
| <property name="limitedTokens" value="EXPR"/> |
| <property name="minimumNumber" value="1"/> |
| </module> |
| </source> |
| |
| <p> |
| A switch within a switch: |
| </p> |
| <source> |
| <module name="DescendantToken"> |
| <property name="tokens" value="LITERAL_SWITCH"/> |
| <property name="limitedTokens" value="LITERAL_SWITCH"/> |
| <property name="maximumNumber" value="0"/> |
| <property name="minimumDepth" value="1"/> |
| </module> |
| </source> |
| |
| <p>A return statement from within a catch or finally block:</p> |
| <source> |
| <module name="DescendantToken"> |
| <property name="tokens" value="LITERAL_FINALLY,LITERAL_CATCH"/> |
| <property name="limitedTokens" value="LITERAL_RETURN"/> |
| <property name="maximumNumber" value="0"/> |
| </module> |
| </source> |
| |
| <p>A try statement within a catch or finally block:</p> |
| <source> |
| <module name="DescendantToken"> |
| <property name="tokens" value="LITERAL_CATCH,LITERAL_FINALLY"/> |
| <property name="limitedTokens" value="LITERAL_TRY"/> |
| <property name="maximumNumber" value="0"/> |
| </module> |
| </source> |
| |
| <p>Too many cases within a switch:</p> |
| <source> |
| <module name="DescendantToken"> |
| <property name="tokens" value="LITERAL_SWITCH"/> |
| <property name="limitedTokens" value="LITERAL_CASE"/> |
| <property name="maximumDepth" value="2"/> |
| <property name="maximumNumber" value="10"/> |
| </module> |
| </source> |
| |
| <p>Too many local variables within a method:</p> |
| <source> |
| <module name="DescendantToken"> |
| <property name="tokens" value="METHOD_DEF"/> |
| <property name="limitedTokens" value="VARIABLE_DEF"/> |
| <property name="maximumDepth" value="2"/> |
| <property name="maximumNumber" value="10"/> |
| </module> |
| </source> |
| |
| <p>Too many returns from within a method:</p> |
| <source> |
| <module name="DescendantToken"> |
| <property name="tokens" value="METHOD_DEF"/> |
| <property name="limitedTokens" value="LITERAL_RETURN"/> |
| <property name="maximumNumber" value="3"/> |
| </module> |
| </source> |
| |
| <p>Too many fields within an interface:</p> |
| <source> |
| <module name="DescendantToken"> |
| <property name="tokens" value="INTERFACE_DEF"/> |
| <property name="limitedTokens" value="VARIABLE_DEF"/> |
| <property name="maximumDepth" value="2"/> |
| <property name="maximumNumber" value="0"/> |
| </module> |
| </source> |
| |
| <p>Limits the number of exceptions a method can throw:</p> |
| <source> |
| <module name="DescendantToken"> |
| <property name="tokens" value="LITERAL_THROWS"/> |
| <property name="limitedTokens" value="IDENT"/> |
| <property name="maximumNumber" value="1"/> |
| </module> |
| </source> |
| |
| <p>Limits the number of expressions in a method:</p> |
| <source> |
| <module name="DescendantToken"> |
| <property name="tokens" value="METHOD_DEF"/> |
| <property name="limitedTokens" value="EXPR"/> |
| <property name="maximumNumber" value="200"/> |
| </module> |
| </source> |
| |
| <p>Disallows empty statements:</p> |
| <source> |
| <module name="DescendantToken"> |
| <property name="tokens" value="EMPTY_STAT"/> |
| <property name="limitedTokens" value="EMPTY_STAT"/> |
| <property name="maximumNumber" value="0"/> |
| <property name="maximumDepth" value="0"/> |
| <property name="maximumMessage" |
| value="Empty statement is not allowed."/> |
| </module> |
| </source> |
| |
| <p>Too many fields within a class:</p> |
| <source> |
| <module name="DescendantToken"> |
| <property name="tokens" value="CLASS_DEF"/> |
| <property name="limitedTokens" value="VARIABLE_DEF"/> |
| <property name="maximumDepth" value="2"/> |
| <property name="maximumNumber" value="10"/> |
| </module> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+DescendantToken"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22descendant.token.max%22"> |
| descendant.token.max</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22descendant.token.min%22"> |
| descendant.token.min</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22descendant.token.sum.max%22"> |
| descendant.token.sum.max</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22descendant.token.sum.min%22"> |
| descendant.token.sum.min</a> |
| </li> |
| </ul> |
| <p> |
| All messages can be customized if the default message doesn't suit you. |
| Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to. |
| </p> |
| </subsection> |
| |
| <subsection name="Package"> |
| <p> |
| com.puppycrawl.tools.checkstyle.checks |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="FinalParameters"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.0</p> |
| <p> |
| Check that parameters for methods, constructors, and catch blocks are |
| final. Interface, abstract, and native methods are not checked: the final |
| keyword does not make sense for interface, abstract, and native method |
| parameters as there is no code that could modify the parameter. |
| </p> |
| |
| <p> |
| Rationale: Changing the value of parameters during the execution of |
| the method's algorithm can be confusing and should be avoided. A |
| great way to let the Java compiler prevent this coding style is to |
| declare parameters final. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>ignorePrimitiveTypes</td> |
| <td>ignore primitive types as parameters</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>false</code></td> |
| <td>6.2</td> |
| </tr> |
| <tr> |
| <td>tokens</td> |
| <td>tokens to check</td> |
| <td> |
| subset of tokens |
| <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_CATCH">LITERAL_CATCH</a>, |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#FOR_EACH_CLAUSE">FOR_EACH_CLAUSE</a>. |
| </td> |
| <td> |
| <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>. |
| </td> |
| <td>3.0</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the check to enforce final parameters for methods and |
| constructors: |
| </p> |
| <source> |
| <module name="FinalParameters"/> |
| </source> |
| |
| <p> |
| To configure the check to enforce final parameters only for |
| constructors: |
| </p> |
| <source> |
| <module name="FinalParameters"> |
| <property name="tokens" value="CTOR_DEF"/> |
| </module> |
| </source> |
| <p> |
| To configure the check to allow ignoring |
| <a href="https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html"> |
| primitive datatypes</a> as parameters: |
| </p> |
| <source> |
| <module name="FinalParameters"> |
| <property name="ignorePrimitiveTypes" value="true"/> |
| </module> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Asun_checks.xml+repo%3Acheckstyle%2Fcheckstyle+FinalParameters"> |
| Sun Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+FinalParameters"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22final.parameter%22"> |
| final.parameter</a> |
| </li> |
| </ul> |
| <p> |
| All messages can be customized if the default message doesn't suit you. |
| Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to. |
| </p> |
| </subsection> |
| |
| <subsection name="Package"> |
| <p> |
| com.puppycrawl.tools.checkstyle.checks |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="Indentation"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.1</p> |
| <p> |
| Checks correct indentation of Java code. |
| </p> |
| |
| <p> |
| The idea behind this is that while pretty printers are |
| sometimes convenient for bulk reformats of legacy code, they often |
| either aren't configurable enough or just can't anticipate how |
| format should be done. Sometimes this is personal preference, other |
| times it is practical experience. In any case, this check should |
| just ensure that a minimal set of indentation rules is followed. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>basicOffset</td> |
| <td>how far new indentation level should be indented when on the next line</td> |
| <td><a href="property_types.html#integer">Integer</a></td> |
| <td>4</td> |
| <td>3.1</td> |
| </tr> |
| <tr> |
| <td>braceAdjustment</td> |
| <td>how far a braces should be indented when on the next line</td> |
| <td><a href="property_types.html#integer">Integer</a></td> |
| <td>0</td> |
| <td>3.1</td> |
| </tr> |
| <tr> |
| <td>caseIndent</td> |
| <td>how far a case label should be indented when on next line</td> |
| <td><a href="property_types.html#integer">Integer</a></td> |
| <td>4</td> |
| <td>3.1</td> |
| </tr> |
| <tr> |
| <td>throwsIndent</td> |
| <td>how far a throws clause should be indented when on next line</td> |
| <td><a href="property_types.html#integer">Integer</a></td> |
| <td>4</td> |
| <td>5.7</td> |
| </tr> |
| <tr> |
| <td>arrayInitIndent</td> |
| <td>how far an array initialisation should be indented when on next line</td> |
| <td><a href="property_types.html#integer">Integer</a></td> |
| <td>4</td> |
| <td>5.8</td> |
| </tr> |
| <tr> |
| <td>lineWrappingIndentation</td> |
| <td>how far continuation line should be indented when line-wrapping is present</td> |
| <td><a href="property_types.html#integer">Integer</a></td> |
| <td>4</td> |
| <td>5.9</td> |
| </tr> |
| <tr> |
| <td>forceStrictCondition</td> |
| <td>force strict indent level in line wrapping case. If value is true, line wrap indent |
| have to be same as lineWrappingIndentation parameter. If value is false, line wrap indent could be bigger on any value user would like.</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td>false</td> |
| <td>6.3</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the check: |
| </p> |
| <source> |
| <module name="Indentation"/> |
| </source> |
| |
| <p> |
| To configure the check to enforce the indentation style recommended by |
| Oracle: |
| </p> |
| |
| <source> |
| <module name="Indentation"> |
| <property name="caseIndent" value="0"/> |
| </module> |
| </source> |
| <p> |
| To configure the Check to enforce strict condition in line-wrapping validation. |
| </p> |
| <source> |
| <module name="Indentation"> |
| <property name="forceStrictCondition" value="true"/> |
| </module> |
| </source> |
| <p> |
| Such config doesn't allow next cases: |
| </p> |
| <source> |
| void foo(String aFooString, |
| int aFooInt) {} // indent:8 ; expected: 4; warn, because 8 != 4 |
| </source> |
| <p> |
| But if forceStrictCondition = false, this code is valid: |
| </p> |
| <source> |
| void foo(String aFooString, |
| int aFooInt) {} // indent:8 ; expected: > 4; ok, because 8 > 4 |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+Indentation"> |
| Google Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+Indentation"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Findentation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22indentation.child.error%22"> |
| indentation.child.error</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Findentation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22indentation.child.error.multi%22"> |
| indentation.child.error.multi</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Findentation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22indentation.error%22"> |
| indentation.error</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Findentation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22indentation.error.multi%22"> |
| indentation.error.multi</a> |
| </li> |
| </ul> |
| <p> |
| All messages can be customized if the default message doesn't suit you. |
| Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to. |
| </p> |
| </subsection> |
| |
| <subsection name="Package"> |
| <p> |
| com.puppycrawl.tools.checkstyle.checks.indentation |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="NewlineAtEndOfFile"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.1</p> |
| <p> |
| Checks whether files end with a line separator. |
| </p> |
| |
| <p> |
| Rationale: Any source files and text files in general should |
| end with a line separator to let other easily add new content |
| at the end of file and "diff" command does not show previous lines as changed. |
| <br/> |
| Example (line 36 should not be in diff): |
| <img src="https://cloud.githubusercontent.com/assets/812984/13894408/afd965b8-ed24-11e5-8bfd-e9edf56a6fe6.png" alt="example of diff"/> |
| </p> |
| <p> |
| Old Rationale: CVS source control management |
| systems will even print a warning when it |
| encounters a file that doesn't end with a line separator. |
| </p> |
| <p> |
| Attention: property fileExtensions works with files that are passed by similar property for at |
| <a href="config.html#Checker">Checker</a>. |
| Please make sure required file extensions are mentioned at Checker's fileExtensions property. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>lineSeparator</td> |
| <td>type of line separator</td> |
| <td> |
| One of "system" (system default), |
| "crlf" (Windows-style), "cr" |
| (Mac-style), "lf" (Unix-style) and "lf_cr_crlf" (lf, cr or crlf). |
| </td> |
| <td>"system"</td> |
| <td>3.1</td> |
| </tr> |
| <tr> |
| <td>fileExtensions</td> |
| <td>file type extension of the files to check.</td> |
| <td><a href="property_types.html#stringSet">String Set</a></td> |
| <td>all files</td> |
| <td>3.1</td> |
| </tr> |
| |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the check: |
| </p> |
| <source> |
| <module name="NewlineAtEndOfFile"/> |
| </source> |
| |
| <p> |
| To configure the check to always use Unix-style line separators: |
| </p> |
| <source> |
| <module name="NewlineAtEndOfFile"> |
| <property name="lineSeparator" value="lf"/> |
| </module> |
| </source> |
| |
| <p> |
| To configure the check to work only on Java, XML and Python files: |
| </p> |
| <source> |
| <module name="NewlineAtEndOfFile"> |
| <property name="fileExtensions" value="java, xml, py"/> |
| </module> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Asun_checks.xml+repo%3Acheckstyle%2Fcheckstyle+NewlineAtEndOfFile"> |
| Sun Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+NewlineAtEndOfFile"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22noNewlineAtEOF%22"> |
| noNewlineAtEOF</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22unable.open%22"> |
| unable.open</a> |
| </li> |
| </ul> |
| <p> |
| All messages can be customized if the default message doesn't suit you. |
| Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to. |
| </p> |
| </subsection> |
| |
| <subsection name="Package"> |
| <p> |
| com.puppycrawl.tools.checkstyle.checks |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#Checker">Checker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="OuterTypeFilename"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 5.3</p> |
| <p> |
| Checks that the outer type name and the file name match. For example, |
| the class <code>Foo</code> must be in a file named |
| <code>Foo.java</code>. |
| </p> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the check: |
| </p> |
| <source> |
| <module name="OuterTypeFilename"/> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+OuterTypeFilename"> |
| Google Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+OuterTypeFilename"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22type.file.mismatch%22"> |
| type.file.mismatch</a> |
| </li> |
| </ul> |
| <p> |
| All messages can be customized if the default message doesn't suit you. |
| Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to. |
| </p> |
| </subsection> |
| |
| <subsection name="Package"> |
| <p> |
| com.puppycrawl.tools.checkstyle.checks |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="TodoComment"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.0</p> |
| <p> |
| A check for <code>TODO:</code> comments. Actually |
| it is a generic <a |
| href="https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">regular |
| expression</a> matcher on Java comments. To check for other |
| patterns in Java comments, set the <code>format</code> property. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>format</td> |
| <td>Pattern to match comments against</td> |
| <td><a href="property_types.html#regexp">Regular Expression</a></td> |
| <td><code>"TODO:"</code></td> |
| <td>3.0</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Notes"> |
| <p> |
| Using <code>TODO:</code> comments is a great way |
| to keep track of tasks that need to be done. Having them |
| reported by Checkstyle makes it very hard to forget about |
| them. |
| </p> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the check: |
| </p> |
| <source> |
| <module name="TodoComment"/> |
| </source> |
| |
| <p> |
| To configure the check for comments that contain <code>TODO</code> and <code>FIXME</code>: |
| </p> |
| <source> |
| <module name="TodoComment"> |
| <property name="format" value="(TODO)|(FIXME)"/> |
| </module> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Asun_checks.xml+repo%3Acheckstyle%2Fcheckstyle+TodoComment"> |
| Sun Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+TodoComment"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22todo.match%22"> |
| todo.match</a> |
| </li> |
| </ul> |
| <p> |
| All messages can be customized if the default message doesn't suit you. |
| Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to. |
| </p> |
| </subsection> |
| |
| <subsection name="Package"> |
| <p> |
| com.puppycrawl.tools.checkstyle.checks |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="TrailingComment"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.4</p> |
| <p> |
| The check to ensure that requires that comments be the only thing on |
| a line. For the case of <code>//</code> comments that means that the only thing |
| that should precede it is whitespace. It doesn't check comments if |
| they do not end a line; for example, it accepts the following: |
| <code>Thread.sleep( 10 <some comment here> );</code> Format |
| property is intended to deal with the "} // while" example. |
| </p> |
| |
| <p> |
| Rationale: Steve McConnell in <cite>Code Complete</cite> suggests that |
| endline comments are a bad practice. An end line comment would be |
| one that is on the same line as actual code. For example: |
| </p> |
| |
| <source> |
| a = b + c; // Some insightful comment |
| d = e / f; // Another comment for this line |
| </source> |
| |
| <p> |
| Quoting <cite>Code Complete</cite> for the justification: |
| </p> |
| |
| <ul> |
| <li> "The comments have to be aligned so that they do not |
| interfere with the visual structure of the code. If you don't align |
| them neatly, they'll make your listing look like it's been through a |
| washing machine." |
| </li> |
| <li> "Endline comments tend to be hard to format...It takes |
| time to align them. Such time is not spent learning more about the |
| code; it's dedicated solely to the tedious task of pressing the |
| spacebar or tab key." |
| </li> |
| <li> "Endline comments are also hard to maintain. If the code |
| on any line containing an endline comment grows, it bumps the |
| comment farther out, and all the other endline comments will have to |
| bumped out to match. Styles that are hard to maintain aren't |
| maintained...." |
| </li> |
| <li> "Endline comments also tend to be cryptic. The right side |
| of the line doesn't offer much room and the desire to keep the |
| comment on one line means the comment must be short. Work then goes |
| into making the line as short as possible instead of as clear as |
| possible. The comment usually ends up as cryptic as |
| possible...." |
| </li> |
| <li> "A systemic problem with endline comments is that it's |
| hard to write a meaningful comment for one line of code. Most |
| endline comments just repeat the line of code, which hurts more than |
| it helps." |
| </li> |
| </ul> |
| |
| <p> |
| McConnel's comments on being hard to maintain when the size of the line |
| changes are even more important in the age of automated |
| refactorings. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>format</td> |
| <td>pattern for strings allowed before the comment</td> |
| <td><a href="property_types.html#regexp">Regular Expression</a></td> |
| <td><code>"^[\s});]*$"</code></td> |
| <td>3.4</td> |
| </tr> |
| <tr> |
| <td>legalComment</td> |
| <td>pattern for text allowed in trailing comments. (This |
| pattern will not be applied to multiline comments and the text of the |
| comment will be trimmed before matching.)</td> |
| <td><a href="property_types.html#regexp">Regular Expression</a></td> |
| <td><code>null</code></td> |
| <td>4.2</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the check: |
| </p> |
| <source> |
| <module name="TrailingComment"/> |
| </source> |
| |
| <p> |
| To configure the check so it enforces only comment on a line: |
| </p> |
| <source> |
| <module name="TrailingComment"> |
| <property name="format" value="^\\s*$"/> |
| </module> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+TrailingComment"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22trailing.comments%22"> |
| trailing.comments</a> |
| </li> |
| </ul> |
| <p> |
| All messages can be customized if the default message doesn't suit you. |
| Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to. |
| </p> |
| </subsection> |
| |
| <subsection name="Package"> |
| <p> |
| com.puppycrawl.tools.checkstyle.checks |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="Translation"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.0</p> |
| <p> |
| A <a href="config.html#Overview">FileSetCheck</a> that ensures |
| the correct translation of code by checking property files for |
| consistency regarding their keys. Two property files |
| describing one and the same context are consistent if they |
| contain the same keys. TranslationCheck also can check an existence of required |
| translations which must exist in project, if 'requiredTranslations' option is used. |
| </p> |
| |
| <p> |
| Consider the following properties file in the same directory: |
| </p> |
| <source> |
| #messages.properties |
| hello=Hello |
| cancel=Cancel |
| |
| #messages_de.properties |
| hell=Hallo |
| ok=OK |
| </source> |
| |
| <p> |
| The Translation check will find the typo in the German <code>hello</code> |
| key, the missing <code>ok</code> key in the default resource file and the |
| missing <code>cancel</code> key in the German resource file: |
| </p> |
| <source> |
| messages_de.properties: Key 'hello' missing. |
| messages_de.properties: Key 'cancel' missing. |
| messages.properties: Key 'hell' missing. |
| messages.properties: Key 'ok' missing. |
| </source> |
| <p> |
| <font color="red">Attention:</font> this Check could produce false-positives if it is used with |
| <a href="config.html#Checker">Checker</a> that use cache (property "cacheFile") |
| This is known design problem, will be addressed at |
| <a href="https://github.com/checkstyle/checkstyle/issues/3539">issue</a>. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>fileExtensions</td> |
| <td> |
| File type extension to identify translation files. Setting |
| this property is typically only required if your |
| translation files are preprocessed and the original files |
| do not have the extension <code>.properties</code> |
| </td> |
| <td><a href="property_types.html#stringSet">String Set</a></td> |
| <td><code>properties</code></td> |
| <td>3.0</td> |
| </tr> |
| <tr> |
| <td>baseName</td> |
| <td><a href="https://docs.oracle.com/javase/7/docs/api/java/util/ResourceBundle.html"> |
| Base name</a> of resource bundles which contain message resources. It helps |
| the check to distinguish config and localization resources.</td> |
| <td><a href="property_types.html#regexp">Regular Expression</a></td> |
| <td><code>"^messages.*$"</code></td> |
| <td>6.17</td> |
| </tr> |
| <tr> |
| <td>requiredTranslations</td> |
| <td> |
| Allows to specify language codes of required translations which must exist in project. |
| Language code is composed of the lowercase, two-letter codes as defined by |
| <a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes">ISO 639-1</a>. |
| Default value is empty String Set which means that only the existence |
| of default translation is checked. Note, if you specify language codes (or just |
| one language code) of required translations the check will also check for |
| existence of default translation files in project. |
| ATTENTION: the check will perform the validation of ISO codes if the option |
| is used. So, if you specify, for example, "mm" for language code, TranslationCheck |
| will rise violation that the language code is incorrect. |
| </td> |
| <td><a href="property_types.html#stringSet">String Set</a></td> |
| <td><code>empty String Set</code></td> |
| <td>6.11</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the check to check only files which have '.properties' and '.translations' |
| extensions: |
| </p> |
| <source> |
| <module name="Translation"> |
| <property name="fileExtensions" value="properties, translations"/> |
| </module> |
| </source> |
| <p> |
| Note, that files with the same path and base name but which have different |
| extensions will be considered as files that belong to different resource bundles. |
| </p> |
| <p> |
| An example of how to configure the check to validate only bundles which base names |
| start with "ButtonLabels": |
| </p> |
| <source> |
| <module name="Translation"> |
| <property name="baseName" value="^ButtonLabels.*$"/> |
| </module> |
| </source> |
| |
| <p> |
| To configure the check to check existence of Japanese and French translations: |
| </p> |
| <source> |
| <module name="Translation"> |
| <property name="requiredTranslations" value="ja, fr"/> |
| </module> |
| </source> |
| <p> |
| The following example shows how the check works if there is a message bundle which |
| element name contains language code, county code, platform name. |
| Consider that we have the below configuration: |
| </p> |
| <source> |
| <module name="Translation"> |
| <property name="requiredTranslations" value="es, fr, de"/> |
| </module> |
| </source> |
| <p> |
| </p> |
| <p> |
| As we can see from the configuration, the TranslationCheck was configured to check |
| an existence of 'es', 'fr' and 'de' translations. Lets assume that we have the resource |
| bundle: |
| </p> |
| <source> |
| messages_home.properties |
| messages_home_es_US.properties |
| messages_home_fr_CA_UNIX.properties |
| </source> |
| <p> |
| Than the check will rise the following violation: |
| "0: Properties file 'messages_home_de.properties' is missing." |
| </p> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Asun_checks.xml+repo%3Acheckstyle%2Fcheckstyle+Translation"> |
| Sun Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+Translation"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22translation.missingKey%22"> |
| translation.missingKey</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22translation.missingTranslationFile%22"> |
| translation.missingTranslationFile</a> |
| </li> |
| </ul> |
| <p> |
| All messages can be customized if the default message doesn't suit you. |
| Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to. |
| </p> |
| </subsection> |
| |
| <subsection name="Package"> |
| <p> |
| com.puppycrawl.tools.checkstyle.checks |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#Checker">Checker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="UncommentedMain"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.2</p> |
| <p> |
| Checks for uncommented main() methods. |
| </p> |
| |
| <p> |
| Rationale: A main() method is often used for debugging |
| purposes. When debugging is finished, developers often forget |
| to remove the method, which changes the API and increases the |
| size of the resulting class or JAR file. With the exception of |
| the real program entry points, all main() methods should be |
| removed or commented out of the sources. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>excludedClasses</td> |
| <td>Pattern for qualified names of classes which are allowed |
| to have a main method.</td> |
| <td><a href="property_types.html#regexp">Regular Expression</a></td> |
| <td><code>"^$"</code></td> |
| <td>3.2</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the check: |
| </p> |
| <source> |
| <module name="UncommentedMain"/> |
| </source> |
| |
| <p> |
| To configure the check to allow the <code>main</code> method for all classes |
| with "Main" name: |
| </p> |
| <source> |
| <module name="UncommentedMain"> |
| <property name="excludedClasses" value="\.Main$"/> |
| </module> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+UncommentedMain"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22uncommented.main%22"> |
| uncommented.main</a> |
| </li> |
| </ul> |
| <p> |
| All messages can be customized if the default message doesn't suit you. |
| Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to. |
| </p> |
| </subsection> |
| |
| <subsection name="Package"> |
| <p> |
| com.puppycrawl.tools.checkstyle.checks |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="UniqueProperties"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 5.7</p> |
| <p> |
| Checks properties files for duplicated properties. |
| </p> |
| <p> |
| Rationale: Multiple property keys usually appear after merge |
| or rebase of several branches. While there are no errors in |
| runtime, there can be a confusion due to having different values |
| for the duplicated properties. |
| </p> |
| |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>fileExtensions</td> |
| <td>file type extension of the files to check.</td> |
| <td><a href="property_types.html#stringSet">String Set</a></td> |
| <td>properties</td> |
| <td>5.7</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the check: |
| </p> |
| <source> |
| <module name="UniqueProperties"> |
| <property name="fileExtensions" value="properties" /> |
| </module> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+UniqueProperties"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22properties.duplicate.property%22"> |
| properties.duplicate.property</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22unable.open.cause%22"> |
| unable.open.cause</a> |
| </li> |
| </ul> |
| <p> |
| All messages can be customized if the default message doesn't suit you. |
| Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to. |
| </p> |
| </subsection> |
| |
| <subsection name="Package"> |
| <p> |
| com.puppycrawl.tools.checkstyle.checks |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#Checker">Checker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="UpperEll"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.0</p> |
| <p> |
| Checks that long constants are defined with an upper ell. That |
| is <code>' L'</code> and not <code>'l'</code>. This is in accordance with the Java |
| Language Specification, <a |
| href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-3.html#jls-3.10.1"> |
| Section 3.10.1</a>. |
| </p> |
| |
| <p> |
| The capital L looks a lot like <code>1</code>. |
| </p> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the check: |
| </p> |
| <source> |
| <module name="UpperEll"/> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+UpperEll"> |
| Google Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Asun_checks.xml+repo%3Acheckstyle%2Fcheckstyle+UpperEll"> |
| Sun Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+UpperEll"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22upperEll%22"> |
| upperEll</a> |
| </li> |
| </ul> |
| <p> |
| All messages can be customized if the default message doesn't suit you. |
| Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to. |
| </p> |
| </subsection> |
| |
| <subsection name="Package"> |
| <p> |
| com.puppycrawl.tools.checkstyle.checks |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| </body> |
| </document> |