| <?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>Class Design</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="DesignForExtension"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.1</p> |
| <p> |
| The check finds classes that are designed for extension (subclass creation). |
| </p> |
| <p> |
| Nothing wrong could be with founded classes. |
| This check makes sense only for library projects (not application projects) |
| which care of ideal OOP-design to make sure that class works in all cases even misusage. |
| Even in library projects this check most likely will find classes that are designed |
| for extension by somebody. User needs to use suppressions extensively to got a benefit from |
| this check, and keep in suppressions all confirmed/known classes that are deigned for |
| inheritance intentionally to let the check catch only new classes, and bring this to |
| team/user attention. |
| </p> |
| <p> |
| ATTENTION: Only user can decide whether a class is designed for extension or not. |
| The check just shows all classes which are possibly designed for extension. |
| If smth inappropriate is found please use suppression. |
| </p> |
| <p> |
| ATTENTION: If the method which can be overridden in a subclass has a javadoc comment |
| (a good practice is to explain its self-use of overridable methods) the check will not |
| rise a violation. The violation can also be skipped if the method which can be overridden |
| in a subclass has one or more annotations that are specified in ignoredAnnotations |
| option. Note, that by default @Override annotation is not included in the |
| ignoredAnnotations set as in a subclass the method which has the annotation can also be |
| overridden in its subclass. |
| </p> |
| <p> |
| Problem is described at "Effective Java, 2nd Edition by Josh Bloch" book, chapter "Item 17: Design and document for inheritance or else prohibit it". |
| </p> |
| <p> |
| Some quotes from book: |
| </p> |
| <blockquote>The class must document its self-use of overridable methods. |
| By convention, a method that invokes overridable methods contains a description |
| of these invocations at the end of its documentation comment. The description |
| begins with the phrase “This implementation.” |
| </blockquote> |
| <blockquote>The best solution to this problem is to prohibit subclassing in classes that |
| are not designed and documented to be safely subclassed. |
| </blockquote> |
| <blockquote>If a concrete class does not implement a standard interface, then you may |
| inconvenience some programmers by prohibiting inheritance. If you feel that you |
| must allow inheritance from such a class, one reasonable approach is to ensure |
| that the class never invokes any of its overridable methods and to document this |
| fact. In other words, eliminate the class’s self-use of overridable methods entirely. |
| In doing so, you’ll create a class that is reasonably safe to subclass. Overriding a |
| method will never affect the behavior of any other method. |
| </blockquote> |
| <p> |
| The check finds classes that have overridable methods (public or protected methods |
| that are non-static, not-final, non-abstract) and have non-empty implementation. |
| </p> |
| |
| <p> |
| Rationale: This library design style protects superclasses against |
| being broken by subclasses. The downside is that subclasses are |
| limited in their flexibility, in particular they cannot prevent |
| execution of code in the superclass, but that also means that |
| subclasses cannot corrupt the state of the superclass by forgetting |
| to call the superclass's method. |
| </p> |
| <p> |
| More specifically, |
| it enforces a programming style where superclasses provide empty |
| "hooks" that can be implemented by subclasses. |
| </p> |
| <p> |
| Example of code that cause violation as it is designed for extension: |
| </p> |
| <source> |
| public abstract class Plant { |
| private String roots; |
| private String trunk; |
| |
| protected void validate() { |
| if (roots == null) throw new IllegalArgumentException("No roots!"); |
| if (trunk == null) throw new IllegalArgumentException("No trunk!"); |
| } |
| |
| public abstract void grow(); |
| } |
| |
| public class Tree extends Plant { |
| private List leaves; |
| |
| @Overrides |
| protected void validate() { |
| super.validate(); |
| if (leaves == null) throw new IllegalArgumentException("No leaves!"); |
| } |
| |
| public void grow() { |
| validate(); |
| } |
| } |
| </source> |
| <p> |
| Example of code without violation: |
| </p> |
| <source> |
| public abstract class Plant { |
| private String roots; |
| private String trunk; |
| |
| private void validate() { |
| if (roots == null) throw new IllegalArgumentException("No roots!"); |
| if (trunk == null) throw new IllegalArgumentException("No trunk!"); |
| validateEx(); |
| } |
| |
| protected void validateEx() { } |
| |
| public abstract void grow(); |
| } |
| </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>ignoredAnnotations</td> |
| <td> |
| Annotations which allow the check to skip the method from validation. |
| </td> |
| <td><a href="property_types.html#stringSet">String Set</a></td> |
| <td><code>Test, Before, After, BeforeClass, AfterClass</code></td> |
| <td>7.2</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the check: |
| </p> |
| |
| <source> |
| <module name="DesignForExtension"/> |
| </source> |
| |
| <p> |
| To configure the check to allow methods which have @Override and @Test annotations to be |
| designed for extension. |
| </p> |
| |
| <source> |
| <module name="DesignForExtension"> |
| <property name="ignoredAnnotations" value="Override, Test"/> |
| </module> |
| </source> |
| |
| <source> |
| public class A extends B { |
| @Override |
| public int foo() { |
| return 2; |
| } |
| |
| public int foo2() {return 8;} // violation |
| } |
| |
| public class B { |
| /** |
| * This implementation ... |
| @return some int value. |
| */ |
| public int foo() { |
| return 1; |
| } |
| |
| public int foo3() {return 3;} // violation |
| } |
| |
| public class FooTest { |
| @Test |
| public void testFoo() { |
| final B b = new A(); |
| assertEquals(2, b.foo()); |
| } |
| |
| public int foo4() {return 4;} // violation |
| } |
| </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+DesignForExtension"> |
| Sun Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+DesignForExtension"> |
| 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%2Fdesign+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22design.forExtension%22"> |
| design.forExtension</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.design |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="FinalClass"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.1</p> |
| <p> |
| Checks that a class which has only private constructors is declared |
| as final. Doesn't check for classes nested in interfaces |
| or annotations, as they are always <code>final</code> there. |
| </p> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the check: |
| </p> |
| <source> |
| <module name="FinalClass"/> |
| </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+FinalClass"> |
| Sun Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+FinalClass"> |
| 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%2Fdesign+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22final.class%22"> |
| final.class</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.design |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="HideUtilityClassConstructor"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.1</p> |
| <p> |
| Makes sure that utility classes (classes that contain only static |
| methods or fields in their API) do not have a public constructor. |
| </p> |
| |
| <p> |
| Rationale: Instantiating utility classes does not make sense. Hence |
| the constructors should either be private or (if you want to allow |
| subclassing) protected. A common mistake is forgetting to hide the |
| default constructor. |
| </p> |
| |
| <p> |
| If you make the constructor protected you may want to consider the |
| following constructor implementation technique to disallow |
| instantiating subclasses: |
| </p> |
| |
| <source> |
| public class StringUtils // not final to allow subclassing |
| { |
| protected StringUtils() { |
| // prevents calls from subclass |
| throw new UnsupportedOperationException(); |
| } |
| |
| public static int count(char c, String s) { |
| // ... |
| } |
| } |
| </source> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the check: |
| </p> |
| <source> |
| <module name="HideUtilityClassConstructor"/> |
| </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+HideUtilityClassConstructor"> |
| Sun Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+HideUtilityClassConstructor"> |
| 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%2Fdesign+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22hide.utility.class%22"> |
| hide.utility.class</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.design |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="InnerTypeLast"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 5.2</p> |
| <p> |
| Check nested (inner) classes/interfaces are declared at the |
| bottom of the class after all method and field declarations. |
| </p> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the check: |
| </p> |
| <source> |
| <module name="InnerTypeLast"/> |
| </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+InnerTypeLast"> |
| 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%2Fdesign+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22arrangement.members.before.inner%22"> |
| arrangement.members.before.inner</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.design |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="InterfaceIsType"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.1</p> |
| <p> |
| Implements Joshua Bloch, Effective Java, Item 17 - Use Interfaces only to |
| define types. |
| </p> |
| |
| <p> |
| According to Bloch, an interface should describe a <em>type</em>. |
| It is therefore inappropriate to define an interface that does not |
| contain any methods but only constants. The Standard class <a |
| href="https://docs.oracle.com/javase/8/docs/api/javax/swing/SwingConstants.html">javax.swing.SwingConstants</a> |
| is an example of a class that would be flagged by this check. |
| </p> |
| |
| <p> |
| The check can be configured to also disallow marker interfaces like |
| <code>java.io.Serializable</code>, that do not contain methods or |
| constants at all. |
| </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>allowMarkerInterfaces</td> |
| <td> |
| Controls whether marker interfaces like Serializable are |
| allowed. |
| </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: |
| </p> |
| <source> |
| <module name="InterfaceIsType"/> |
| </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+InterfaceIsType"> |
| Sun Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+InterfaceIsType"> |
| 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%2Fdesign+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22interface.type%22"> |
| interface.type</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.design |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="MutableException"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.2</p> |
| <p> |
| Ensures that exception classes (classes with names conforming to some regular |
| expression and explicitly extending classes with names conforming to other |
| regular expression) are immutable, that is, that they have only final fields. |
| </p> |
| |
| <p> |
| The current algorithm is very simple: it checks that all members of |
| exception are final. The user can still mutate an exception's instance |
| (e.g. Throwable has a method called <code>setStackTrace</code> |
| which changes the exception's stack trace). But, at least, all information |
| provided by this exception type is unchangeable. |
| </p> |
| |
| <p> |
| Rationale: Exception instances should represent an error |
| condition. Having non final fields not only allows the state to be |
| modified by accident and therefore mask the original condition but |
| also allows developers to accidentally forget to set the initial state. |
| In both cases, code catching the exception could draw incorrect |
| conclusions based on the state. |
| </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 exception class names</td> |
| <td><a href="property_types.html#regexp">Regular Expression</a></td> |
| <td><code>"^.*Exception$|^.*Error$|^.*Throwable$"</code></td> |
| <td>3.2</td> |
| </tr> |
| <tr> |
| <td>extendedClassNameFormat</td> |
| <td>pattern for extended class names</td> |
| <td><a href="property_types.html#regexp">Regular Expression</a></td> |
| <td><code>"^.*Exception$|^.*Error$|^.*Throwable$"</code></td> |
| <td>6.2</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the check: |
| </p> |
| <source> |
| <module name="MutableException"/> |
| </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+MutableException"> |
| 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%2Fdesign+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22mutable.exception%22"> |
| mutable.exception</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.design |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="OneTopLevelClass"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 5.8</p> |
| <p> |
| Checks that each top-level class, interface or |
| enum resides in a source file of its own. |
| Official description of a 'top-level' term:<a |
| href="https://docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7.6">7.6. Top Level Type Declarations</a>. |
| If file doesn't contains public class, enum or interface, |
| top-level type is the first type in file. |
| </p> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| An example of check's configuration: |
| </p> |
| <source> |
| <module name="OneTopLevelClass"/> |
| </source> |
| <p> |
| <b>ATTENTION:</b> This Check does not support customization of validated tokens, so do not use the "tokens" property. |
| </p> |
| <p> |
| An example of code with violations: |
| </p> |
| <source> |
| public class Foo{ |
| //methods |
| } |
| |
| class Foo2{ |
| //methods |
| } |
| </source> |
| <p> |
| An example of code without public top-level type: |
| </p> |
| <source> |
| class Foo{ // top-level class |
| //methods |
| } |
| |
| class Foo2{ |
| //methods |
| } |
| </source> |
| <p> |
| An example of code without violations: |
| </p> |
| <source> |
| public class Foo{ |
| //methods |
| } |
| </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+OneTopLevelClass"> |
| Google Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+OneTopLevelClass"> |
| 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%2Fdesign+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22one.top.level.class%22"> |
| one.top.level.class</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.design |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="ThrowsCount"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.2</p> |
| <p> |
| Restricts throws statements to a specified count (4 by default). |
| Methods with "Override" or "java.lang.Override" annotation are skipped |
| from validation as current class cannot change signature of these methods. |
| </p> |
| |
| <p> |
| Rationale: Exceptions form part of a method's interface. Declaring a |
| method to throw too many differently rooted exceptions makes |
| exception handling onerous and leads to poor programming practices |
| such as writing code like <code>catch(Exception ex)</code>. |
| 4 is the empirical value which is based on reports that we had for |
| the ThrowsCountCheck over big projects such as OpenJDK. |
| This check also forces developers to put exceptions into a hierarchy |
| such that in the simplest case, only one type of exception need be |
| checked for by a caller but any subclasses can be caught specifically |
| if necessary.For more information on rules for the exceptions and |
| their issues, see Effective Java: Programming Language Guide |
| Second Edition by Joshua Bloch pages 264-273. |
| </p> |
| |
| <p> |
| <b>ignorePrivateMethods</b> - allows to skip private methods as they do |
| not cause problems for other classes. |
| </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>max</td> |
| <td>maximum allowed number of throws statements</td> |
| <td><a href="property_types.html#integer">Integer</a></td> |
| <td><code>4</code></td> |
| <td>3.2</td> |
| </tr> |
| <tr> |
| <td>ignorePrivateMethods</td> |
| <td>whether private methods must be ignored</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>true</code></td> |
| <td>6.7</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the check so that it doesn't allow more than two throws |
| per method: |
| </p> |
| <source> |
| <module name="ThrowsCount"> |
| <property name="max" value="2"/> |
| </module> |
| </source> |
| |
| <p> |
| To configure the check so that it doesn't skip private methods: |
| </p> |
| <source> |
| <module name="ThrowsCount"> |
| <property name="ignorePrivateMethods" value="false"/> |
| </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+ThrowsCount"> |
| 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%2Fdesign+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22throws.count%22"> |
| throws.count</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.design |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="VisibilityModifier"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.0</p> |
| <p> |
| Checks visibility of class members. Only static final, immutable or annotated |
| by specified annotation members may be public; other class members must be private |
| unless the property <code>protectedAllowed</code> or <code>packageAllowed</code> is set. |
| </p> |
| |
| <p> |
| Public members are not flagged if the name matches the public |
| member regular expression (contains <code>"^serialVersionUID$"</code> by default). |
| </p> |
| <p>Note that |
| Checkstyle 2 used to include <code>"^f[A-Z][a-zA-Z0-9]*$"</code> in the default |
| pattern to allow names used in container-managed persistence for Enterprise JavaBeans (EJB) 1.1 with the default settings. |
| With EJB 2.0 it is no longer necessary to have public access |
| for persistent fields, so the default has been changed. |
| </p> |
| |
| <p> |
| Rationale: Enforce encapsulation. |
| </p> |
| <p> |
| Check also has options making it less strict: |
| </p> |
| <p> |
| <b>ignoreAnnotationCanonicalNames</b> - the list of annotations which ignore variables |
| in consideration. If user will provide short annotation name that type will match to any |
| named the same type without consideration of package |
| </p> |
| <p> |
| <b>allowPublicFinalFields</b> - which allows public final fields. |
| Default value is <b>false</b> |
| </p> |
| <p> |
| <b>allowPublicImmutableFields</b> - which allows immutable fields to be declared as |
| public if defined in final class. Default value is <b>false</b> |
| </p> |
| <p> |
| Field is known to be immutable if: |
| - It's declared as final |
| - Has either a primitive type or instance of class user defined to be immutable |
| (such as String, ImmutableCollection from Guava and etc) |
| </p> |
| <p> |
| Classes known to be immutable are listed in <b>immutableClassCanonicalNames</b> by their |
| <b>canonical</b> names. |
| </p> |
| <p> |
| Rationale: Forcing all fields of class to have private modified by default is good |
| in most cases, but in some cases it drawbacks in too much boilerplate get/set code. |
| One of such cases are immutable classes. |
| </p> |
| <p> |
| <b>Restriction</b>: Check doesn't check if class is immutable, there's no |
| checking if accessory methods are missing and all fields are immutable, we only check |
| <b>if current field is immutable or final</b>. Under the flag |
| <b>allowPublicImmutableFields</b>, the enclosing class must also be final, to encourage |
| immutability. Under the flag <b>allowPublicFinalFields</b>, the final modifier on |
| the enclosing class is optional. |
| </p> |
| <p> |
| Star imports are out of scope of this Check. So if one of type imported via |
| <b>star import</b> collides with user specified one by its short name - |
| there won't be Check's violation. |
| </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>packageAllowed</td> |
| <td>whether package visible members are allowed</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>false</code></td> |
| <td>3.0</td> |
| </tr> |
| <tr> |
| <td>protectedAllowed</td> |
| <td>whether protected members are allowed</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>false</code></td> |
| <td>3.0</td> |
| </tr> |
| <tr> |
| <td>publicMemberPattern</td> |
| <td>pattern for public members that should be ignored</td> |
| <td><a href="property_types.html#regexp">Regular Expression</a></td> |
| <td><code>"^serialVersionUID$"</code></td> |
| <td>3.0</td> |
| </tr> |
| <tr> |
| <td>allowPublicFinalFields</td> |
| <td>allows public final fields</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>false</code></td> |
| <td>7.0</td> |
| </tr> |
| <tr> |
| <td>allowPublicImmutableFields</td> |
| <td>allows immutable fields to be declared as public if defined in final class</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>false</code></td> |
| <td>6.4</td> |
| </tr> |
| <tr> |
| <td>immutableClassCanonicalNames</td> |
| <td>immutable classes canonical names</td> |
| <td><a href="property_types.html#stringSet">String Set</a></td> |
| <td>java.lang.String, java.lang.Integer, java.lang.Byte, java.lang.Character, |
| java.lang.Short, java.lang.Boolean, java.lang.Long, java.lang.Double, java.lang.Float, |
| java.lang.StackTraceElement, java.math.BigInteger, java.math.BigDecimal, java.io.File, |
| java.util.Locale, java.util.UUID, java.net.URL, java.net.URI, |
| java.net.Inet4Address, java.net.Inet6Address, java.net.InetSocketAddress,</td> |
| <td>6.4.1</td> |
| </tr> |
| <tr> |
| <td>ignoreAnnotationCanonicalNames</td> |
| <td>ignore annotations canonical names</td> |
| <td><a href="property_types.html#stringSet">String Set</a></td> |
| <td>org.junit.Rule, org.junit.ClassRule, com.google.common.annotations.VisibleForTesting</td> |
| <td>6.5</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the check: |
| </p> |
| <source> |
| <module name="VisibilityModifier"/> |
| </source> |
| |
| <p> |
| To configure the check so that it allows package visible members: |
| </p> |
| <source> |
| <module name="VisibilityModifier"> |
| <property name="packageAllowed" value="true"/> |
| </module> |
| </source> |
| |
| <p> |
| To configure the check so that it allows no public members: |
| </p> |
| <source> |
| <module name="VisibilityModifier"> |
| <property name="publicMemberPattern" value="^$"/> |
| </module> |
| </source> |
| <p> |
| To configure the Check so that it allows public immutable fields |
| (mostly for immutable classes): |
| </p> |
| <source> |
| <module name="VisibilityModifier"> |
| <property name="allowPublicImmutableFields" value="true"/> |
| </module> |
| </source> |
| <p> |
| Example of allowed public immutable fields: |
| </p> |
| <source> |
| public class ImmutableClass |
| { |
| public final ImmutableSet<String> includes; // No warning |
| public final ImmutableSet<String> excludes; // No warning |
| public final java.lang.String notes; // No warning |
| public final BigDecimal value; // No warning |
| |
| public ImmutableClass(Collection<String> includes, Collection<String> excludes, |
| BigDecimal value, String notes) |
| { |
| this.includes = ImmutableSet.copyOf(includes); |
| this.excludes = ImmutableSet.copyOf(excludes); |
| this.value = value; |
| this.notes = notes; |
| } |
| } |
| </source> |
| <p> |
| To configure the Check in order to allow user specified immutable class names: |
| </p> |
| <source> |
| <module name="VisibilityModifier"> |
| <property name="allowPublicImmutableFields" value="true"/> |
| <property name="immutableClassCanonicalNames" value=" |
| com.google.common.collect.ImmutableSet"/> |
| </module> |
| </source> |
| <p> |
| Example of allowed public immutable fields: |
| </p> |
| <source> |
| public class ImmutableClass |
| { |
| public final ImmutableSet<String> includes; // No warning |
| public final ImmutableSet<String> excludes; // No warning |
| public final java.lang.String notes; // Warning here because |
| //'java.lang.String' wasn't specified as allowed class |
| public final int someValue; // No warning |
| |
| public ImmutableClass(Collection<String> includes, Collection<String> excludes, |
| String notes, int someValue) |
| { |
| this.includes = ImmutableSet.copyOf(includes); |
| this.excludes = ImmutableSet.copyOf(excludes); |
| this.value = value; |
| this.notes = notes; |
| this.someValue = someValue; |
| } |
| } |
| </source> |
| |
| <p> |
| Note, if allowPublicImmutableFields is set to true, the check will also check whether |
| generic type parameters are immutable. If at least one generic type parameter is mutable, |
| there will be a violation. |
| </p> |
| <source> |
| <module name="VisibilityModifier"> |
| <property name="allowPublicImmutableFields" value="true"/> |
| <property name="immutableClassCanonicalNames" value=" |
| com.google.common.collect.ImmutableSet, com.google.common.collect.ImmutableMap,java.lang.String"/> |
| </module> |
| </source> |
| <p> |
| Example of how the check works: |
| </p> |
| <source> |
| public final class Test { |
| public final String s; |
| public final ImmutableSet<String> names; |
| public final ImmutableSet<Object> objects; // violation (Object class is mutable) |
| public final ImmutableMap<String, Object> links; // violation (Object class is mutable) |
| |
| public Test() { |
| s = "Hello!"; |
| names = ImmutableSet.of(); |
| objects = ImmutableSet.of(); |
| links = ImmutableMap.of(); |
| } |
| } |
| </source> |
| <p> |
| To configure the Check passing fields annotated with @com.annotation.CustomAnnotation: |
| </p> |
| <source> |
| <module name="VisibilityModifier"> |
| <property name="ignoreAnnotationCanonicalNames" value= |
| "com.annotation.CustomAnnotation"/> |
| </module> |
| </source> |
| <p> |
| Example of allowed field: |
| </p> |
| <source> |
| class SomeClass |
| { |
| @com.annotation.CustomAnnotation |
| String annotatedString; // no warning |
| @CustomAnnotation |
| String shortCustomAnnotated; // no warning |
| } |
| </source> |
| |
| <p> |
| To configure the Check passing fields annotated with @org.junit.Rule, @org.junit.ClassRule and |
| @com.google.common.annotations.VisibleForTesting annotations: |
| </p> |
| <source> |
| <module name="VisibilityModifier"/> |
| </source> |
| <p> |
| Example of allowed fields: |
| </p> |
| <source> |
| class SomeClass |
| { |
| @org.junit.Rule |
| public TemporaryFolder publicJUnitRule = new TemporaryFolder(); // no warning |
| @org.junit.ClassRule |
| public static TemporaryFolder publicJUnitClassRule = new TemporaryFolder(); // no warning |
| @com.google.common.annotations.VisibleForTesting |
| public String testString = ""; // no warning |
| } |
| </source> |
| |
| <p> |
| To configure the Check passing fields annotated with short annotation name: |
| </p> |
| <source> |
| <module name="VisibilityModifier"> |
| <property name="ignoreAnnotationCanonicalNames" |
| value="CustomAnnotation"/> |
| </module> |
| </source> |
| <p> |
| Example of allowed fields: |
| </p> |
| <source> |
| class SomeClass |
| { |
| @CustomAnnotation |
| String customAnnotated; // no warning |
| @com.annotation.CustomAnnotation |
| String customAnnotated1; // no warning |
| @mypackage.annotation.CustomAnnotation |
| String customAnnotatedAnotherPackage; // another package but short name matches |
| // so no violation |
| } |
| </source> |
| |
| <p> |
| To understand the difference between allowPublicImmutableFields and |
| allowPublicFinalFields options, please, study the following examples. |
| </p> |
| <p> |
| 1) To configure the check to use only 'allowPublicImmutableFields' option: |
| </p> |
| <source> |
| <module name="VisibilityModifier"> |
| <property name="allowPublicImmutableFields" value="true"/> |
| </module> |
| </source> |
| <p> |
| Code example: |
| </p> |
| <source> |
| public class InputPublicImmutable { |
| public final int someIntValue; // violation |
| public final ImmutableSet<String> includes; // violation |
| public final java.lang.String notes; // violation |
| public final BigDecimal value; // violation |
| public final List list; // violation |
| |
| public InputPublicImmutable(Collection<String> includes, |
| BigDecimal value, String notes, int someValue, List l) { |
| this.includes = ImmutableSet.copyOf(includes); |
| this.value = value; |
| this.notes = notes; |
| this.someIntValue = someValue; |
| this.list = l; |
| } |
| } |
| </source> |
| <p> |
| 2) To configure the check to use only 'allowPublicFinalFields' option: |
| </p> |
| <source> |
| <module name="VisibilityModifier"> |
| <property name="allowPublicFinalFields" value="true"/> |
| </module> |
| </source> |
| <p> |
| Code example: |
| </p> |
| <source> |
| public class InputPublicImmutable { |
| public final int someIntValue; |
| public final ImmutableSet<String> includes; |
| public final java.lang.String notes; |
| public final BigDecimal value; |
| public final List list; |
| |
| public InputPublicImmutable(Collection<String> includes, |
| BigDecimal value, String notes, int someValue, List l) { |
| this.includes = ImmutableSet.copyOf(includes); |
| this.value = value; |
| this.notes = notes; |
| this.someIntValue = someValue; |
| this.list = l; |
| } |
| } |
| </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+VisibilityModifier"> |
| Sun Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+VisibilityModifier"> |
| 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%2Fdesign+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22variable.notPrivate%22"> |
| variable.notPrivate</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.design |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| </body> |
| </document> |