ArrayTrailingComma

Since Checkstyle 3.2

Description

Checks that array initialization contains a trailing comma.

int[] a = new int[]
{
  1,
  2,
  3,
};
        

The check demands a comma at the end if neither left nor right curly braces are on the same line as the last element of the array.

return new int[] { 0 };
return new int[] { 0
  };
return new int[] {
  0 };
        

Rationale: Putting this comma in makes it easier to change the order of the elements or add new elements on the end. Main benefit of a trailing comma is that when you add new entry to an array, no surrounding lines are changed.

{
  100000000000000000000,
  200000000000000000000, // OK
}

{
  100000000000000000000,
  200000000000000000000,
  300000000000000000000,  // Just this line added, no other changes
}
        

If closing brace is on the same line as training comma, this benefit is gone (as the check does not demand a certain location of curly braces the following two cases will not produce a violation):

{100000000000000000000,
 200000000000000000000,} // Trailing comma not needed, line needs to be modified anyway

{100000000000000000000,
 200000000000000000000, // Modified line
 300000000000000000000,} // Added line
        

If opening brace is on the same line as training comma there's also (more arguable) problem:

{100000000000000000000, // Line cannot be just duplicated to slightly modify entry
}

{100000000000000000000,
 100000000000000000001, // More work needed to duplicate
}
        

Examples

To configure the check:

<module name="ArrayTrailingComma"/>
          

Which results in the following violations:

int[] numbers = {1, 2, 3};        //no violation
boolean[] bools = {
true,
true,
false
};        //violation

String[][] text = {{},{},};        //no violation

double[][] decimals = {
{0.5, 2.3, 1.1,},        //no violation
{1.7, 1.9, 0.6},
{0.8, 7.4, 6.5}
};        // violation as previous line misses a comma

char[] chars = {'a', 'b', 'c'
  };        / /no violation

String[] letters = {
  "a", "b", "c"};        // no violation

int[] a1 = new int[]{
  1,
  2
  ,
};        // no violation

int[] a2 = new int[]{
  1,
  2
  ,};        // no violation
          

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

AvoidInlineConditionals

Since Checkstyle 3.1

Description

Detects inline conditionals. Here is one example of an inline conditional:

String a = getParameter("a");
String b = (a==null || a.length<1) ? null : a.substring(1);
        

Rationale: Some developers find inline conditionals hard to read, so their employer's coding standards forbid them.

Examples

To configure the check:

<module name="AvoidInlineConditionals"/>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

CovariantEquals

Since Checkstyle 3.2

Description

Checks that classes which define a covariant equals() method also override method equals(Object).

Covariant equals() - method that is similar to equals(Object), but with a covariant parameter type (any subtype of Object).

Notice: the enums are also checked, even though they cannot override equals(Object). The reason is to point out that implementing equals() in enums is considered an awful practice: it may cause having two different enum values that are equal using covariant enum method, and not equal when compared normally.

Inspired by Finding Bugs is Easy, chapter '2.3.1 Bad Covariant Definition of Equals (Eq)':

Java classes may override the equals(Object) method to define a predicate for object equality. This method is used by many of the Java runtime library classes; for example, to implement generic containers.

Programmers sometimes mistakenly use the type of their class Foo as the type of the parameter to equals():

public boolean equals(Foo obj) {...}
        

This covariant version of equals() does not override the version in the Object class, and it may lead to unexpected behavior at runtime, especially if the class is used with one of the standard collection classes which expect that the standard equals(Object) method is overridden.

This kind of bug is not obvious because it looks correct, and in circumstances where the class is accessed through the references of the class type (rather than a supertype), it will work correctly. However, the first time it is used in a container, the behavior might be mysterious. For these reasons, this type of bug can elude testing and code inspections.

Examples

To configure the check:

<module name="CovariantEquals"/>
        

For example:

class Test {
  public boolean equals(Test i) {  // violation
    return false;
  }
}
        

The same class without violations:

class Test {
  public boolean equals(Test i) {  // no violation
    return false;
  }

  public boolean equals(Object i) {
    return false;
  }
}
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

DeclarationOrder

Since Checkstyle 3.2

Description

Checks the order in which parts of the class or interface declaration are defined.

According to Code Conventions for the Java Programming Language , the parts of a class or interface declaration should appear in the following order:

  1. Class (static) variables. First the public class variables, then protected, then package level (no access modifier), and then private.
  2. Instance variables. First the public class variables, then protected, then package level (no access modifier), and then private.
  3. Constructors
  4. Methods

Purpose of ignore* option is to ignore related violations, however it still impacts on other class members.

ATTENTION: the check skips class fields which have forward references from validation due to the fact that we have Checkstyle's limitations to clearly detect user intention of fields location and grouping. For example:

public class A {
  private double x = 1.0;
  private double y = 2.0;
  public double slope = x / y; // will be skipped from validation due to forward reference
}
        

Properties

name description type default value since
ignoreConstructors control whether to ignore constructors. Boolean false 5.2
ignoreModifiers control whether to ignore modifiers (fields, ...). Boolean false 5.2

Examples

To configure the check:

<module name="DeclarationOrder"/>
        

With default options:

class K {
  int a;
  void m(){}
  K(){}  <-- "Constructor definition in wrong order"
  int b; <-- "Instance variable definition in wrong order"
}
        

With ignoreConstructors option:

class K {
  int a;
  void m(){}
  K(){}
  int b; <-- "Instance variable definition in wrong order"
}
        

With ignoreConstructors option and without a method definition in a source class:

class K {
  int a;
  K(){}
  int b; <-- "Instance variable definition in wrong order"
}
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

DefaultComesLast

Since Checkstyle 3.4

Description

Check that the default is after all the cases in a switch statement.

Rationale: Java allows default anywhere within the switch statement. But it is more readable if it comes after the last case.

Properties

name description type default value since
skipIfLastAndSharedWithCase Control whether to allow default along with case if they are not last. Boolean false 7.7

Examples

To configure the check:

<module name="DefaultComesLast"/>
        

To configure the check for skipIfLastAndSharedWithCase:

<module name="DefaultComesLast">
  <property name="skipIfLastAndSharedWithCase" value="true"/>
</module>
        

Example when skipIfLastAndSharedWithCase is set to true.

switch (i) {
  case 1:
    break;
  case 2:
  default: // No violation with the new option is expected
    break;
  case 3:
    break;
}
switch (i) {
  case 1:
    break;
  default: // violation with the new option is expected
  case 2:
    break;
}
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

EmptyStatement

Since Checkstyle 3.1

Description

Detects empty statements (standalone {@code ";"} semicolon). Empty statements often introduce bugs that are hard to spot, such as in

if (someCondition);
  doConditionalStuff();
doUnconditionalStuff();
        

Examples

To configure the check:

<module name="EmptyStatement"/>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

EqualsAvoidNull

Since Checkstyle 5.0

Description

Checks that any combination of String literals is on the left side of an equals() comparison. Also checks for String literals assigned to some field (such as someString.equals(anotherString = "text")).

Rationale: Calling the equals() method on String literals will avoid a potential NullPointerException. Also, it is pretty common to see null checks right before equals comparisons, which is not necessary in the example below.

For example, this code:

String nullString = null;
nullString.equals("My_Sweet_String");
        

should be refactored to:

String nullString = null;
"My_Sweet_String".equals(nullString);
        

Properties

name description type default value since
ignoreEqualsIgnoreCase Control whether to ignore String.equalsIgnoreCase(String) invocations. Boolean false 5.4

Examples

To configure the check:

<module name="EqualsAvoidNull"/>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

EqualsHashCode

Since Checkstyle 3.0

Description

Checks that classes that either override equals() or hashCode() also overrides the other. This check only verifies that the method declarations match Object.equals(Object) and Object.hashCode() exactly to be considered an override. This check does not verify invalid method names, parameters other than Object, or anything else.

Rationale: The contract of equals() and hashCode() requires that equal objects have the same hashCode. Therefore, whenever you override equals() you must override hashCode() to ensure that your class can be used in hash-based collections.

Examples

To configure the check:

<module name="EqualsHashCode"/>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

ExplicitInitialization

Since Checkstyle 3.2

Description

Checks if any class or object member is explicitly initialized to default for its type value (null for object references, zero for numeric types and char and false for boolean.

Rationale: Each instance variable gets initialized twice, to the same value. Java initializes each instance variable to its default value (0 or null) before performing any initialization specified in the code. So there is a minor inefficiency.

Properties

name description type default value since
onlyObjectReferences control whether only explicit initializations made to null for objects should be checked. Boolean false 7.8

Examples

To configure the check:

<module name="ExplicitInitialization"/>
        

To configure the check so that it only checks for objects that explicitly initialize to null:

<module name="ExplicitInitialization">
  <property name="onlyObjectReferences" value="true"/>
</module>
        

Example:

public class Test {
  private int a = 0;
  private int b = 1;
  private int c = 2;

  private boolean a = true;
  private boolean b = false;
  private boolean c = true;
  private boolean d = false;
  private boolean e = false;

  private A a = new A();
  private A b = null; // violation
  private C c = null; // violation
  private D d = new D();

  int ar1[] = null; // violation
  int ar2[] = new int[];
  int ar3[];
  private Bar<String> bar = null; // violation
  private Bar<String>[] barArray = null; // violation

  public static void main( String [] args ) {
  }
}
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

FallThrough

Since Checkstyle 3.4

Description

Checks for fall-through in switch statements. Finds locations where a case contains Java code but lacks a break, return, throw or continue statement.

The check honors special comments to suppress the warning. By default the text "fallthru", "fall through", "fallthrough", "falls through" and "fallsthrough" are recognized (case sensitive). The comment containing these words must be all on one line, and must be on the last non-empty line before the case triggering the warning or on the same line before the case (ugly, but possible).

switch (i) {
case 0:
  i++; // fall through

case 1:
  i++;
  // falls through
case 2:
case 3:
case 4: {
  i++;
}
// fallthrough
case 5:
  i++;
/* fallthru */case 6:
  i++
  break;
}
        

Note: The check assumes that there is no unreachable code in the case.

The following fragment of code will NOT trigger the check, because of the comment "fallthru" and absence of any Java code in case 5.

case 3:
    x = 2;
    // fallthru
case 4:
case 5:
case 6:
    break;
        

Properties

name description type default value since
checkLastCaseGroup Control whether the last case group must be checked. Boolean false 4.0
reliefPattern Define the RegExp to match the relief comment that suppresses the warning about a fall through. Regular Expression "fallthru|falls? ?through" 4.0

Examples

To configure the check:

<module name="FallThrough"/>
        

or

<module name="FallThrough">
  <property name="reliefPattern" value="continue in next case"/>
</module>
        

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

FinalLocalVariable

Since Checkstyle 3.2

Description

Checks that local variables that never have their values changed are declared final. The check can be configured to also check that unchanged parameters are declared final.

Notes

When configured to check parameters, the check ignores parameters of interface methods and abstract methods.

Properties

name description type default value since
validateEnhancedForLoopVariable Control whether to check enhanced for-loop variable. Boolean false 6.5
tokens tokens to check subset of tokens VARIABLE_DEF, PARAMETER_DEF. VARIABLE_DEF. 3.2

Examples

To configure the check:

<module name="FinalLocalVariable"/>
        

To configure the check so that it checks local variables and parameters:

<module name="FinalLocalVariable">
  <property name="tokens" value="VARIABLE_DEF,PARAMETER_DEF"/>
</module>
        

By default, this Check skip final validation on Enhanced For-Loop.

Option 'validateEnhancedForLoopVariable' could be used to make Check to validate even variable from Enhanced For Loop.

An example of how to configure the check so that it also validates enhanced For Loop Variable is:

<module name="FinalLocalVariable">
  <property name="tokens" value="VARIABLE_DEF"/>
  <property name="validateEnhancedForLoopVariable" value="true"/>
</module>
         

Example:

for (int number : myNumbers) { // violation
  System.out.println(number);
}
         

An example of how to configure check on local variables and parameters but do not validate loop variables:

 <module name="FinalLocalVariable">
   <property name="tokens" value="VARIABLE_DEF,PARAMETER_DEF"/>
   <property name="validateEnhancedForLoopVariable" value="false"/>
 </module>
         

Example:

public class MyClass {
  static int foo(int x, int y) { //violations, parameters should be final
    return x+y;
  }
  public static void main (String []args) { //violation, parameters should be final
    for (String i : args) {
      System.out.println(i);
    }
    int result=foo(1,2); // violation
  }
}
         

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

HiddenField

Since Checkstyle 3.0

Description

Checks that a local variable or a parameter does not shadow a field that is defined in the same class.

Notes

It is possible to configure the check to ignore all property setter methods.

A method is recognized as a setter if it is in the following form

${returnType} set${Name}(${anyType} ${name}) { ... }
        

where ${anyType} is any primitive type, class or interface name; ${name} is name of the variable that is being set and ${Name} its capitalized form that appears in the method name. By default it is expected that setter returns void, i.e. ${returnType} is 'void'. For example

void setTime(long time) { ... }
        

Any other return types will not let method match a setter pattern. However, by setting setterCanReturnItsClass property to true definition of a setter is expanded, so that setter return type can also be a class in which setter is declared. For example

class PageBuilder {
  PageBuilder setName(String name) { ... }
}
        

Such methods are known as chain-setters and a common when Builder-pattern is used. Property setterCanReturnItsClass has effect only if ignoreSetter is set to true.

Properties

name description type default value since
ignoreFormat Define the RegExp for names of variables and parameters to ignore. Regular Expression null 3.2
ignoreConstructorParameter Control whether to ignore constructor parameters. Boolean false 3.2
ignoreSetter Allow to ignore the parameter of a property setter method. Boolean false 3.2
setterCanReturnItsClass Allow to expand the definition of a setter method to include methods that return the class' instance. Boolean false 6.3
ignoreAbstractMethods Control whether to ignore parameters of abstract methods. Boolean false 4.0
tokens tokens to check subset of tokens VARIABLE_DEF, PARAMETER_DEF, LAMBDA. VARIABLE_DEF, PARAMETER_DEF, LAMBDA. 3.0

Examples

To configure the check:

<module name="HiddenField"/>
        

To configure the check so that it checks local variables but not parameters:

<module name="HiddenField">
  <property name="tokens" value="VARIABLE_DEF"/>
</module>
        

To configure the check so that it ignores the variables and parameters named "test":

<module name="HiddenField">
  <property name="ignoreFormat" value="^test$"/>
</module>
        
class SomeClass
{
  private List<String> test;

  private void addTest(List<String> test) // no violation
  {
    this.test.addAll(test);
  }

  private void foo()
  {
    final List<String> test = new ArrayList<>(); // no violation
    ...
  }
}
        

To configure the check so that it ignores constructor parameters:

<module name="HiddenField">
  <property name="ignoreConstructorParameter" value="true"/>
</module>
        

To configure the check so that it ignores the parameter of setter methods:

<module name="HiddenField">
  <property name="ignoreSetter" value="true"/>
</module>
        

To configure the check so that it ignores the parameter of setter methods recognizing setter as returning either void or a class in which it is declared:

<module name="HiddenField">
  <property name="ignoreSetter" value="true"/>
  <property name="setterCanReturnItsClass" value="true"/>
</module>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

IllegalCatch

Since Checkstyle 3.2

Description

Checks that certain exception types do not appear in a catch statement.

Rationale: catching java.lang.Exception, java.lang.Error or java.lang.RuntimeException is almost never acceptable. Novice developers often simply catch Exception in an attempt to handle multiple exception classes. This unfortunately leads to code that inadvertently catches NullPointerException, OutOfMemoryError, etc.

Properties

name description type default value since
illegalClassNames Specify exception class names to reject. String Set java.lang.Throwable, RuntimeException, Error, Throwable, java.lang.Error, java.lang.RuntimeException, Exception, java.lang.Exception 3.2

Examples

To configure the check:

<module name="IllegalCatch"/>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

IllegalInstantiation

Since Checkstyle 3.0

Description

Checks for illegal instantiations where a factory method is preferred.

Rationale: Depending on the project, for some classes it might be preferable to create instances through factory methods rather than calling the constructor.

A simple example is the java.lang.Boolean class. For performance reasons, it is preferable to use the predefined constants TRUE and FALSE. Constructor invocations should be replaced by calls to Boolean.valueOf().

Some extremely performance sensitive projects may require the use of factory methods for other classes as well, to enforce the usage of number caches or object pools.

Notes

There is a limitation that it is currently not possible to specify array classes.

Properties

name description type default value since
classes Specify fully qualified class names that should not be instantiated. String Set {} 3.0
tokens tokens to check subset of tokens CLASS_DEF. CLASS_DEF. 3.0

Examples

To configure the check to find instantiations of java.lang.Boolean:

<module name="IllegalInstantiation">
  <property name="classes" value="java.lang.Boolean"/>
</module>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

IllegalThrows

Since Checkstyle 4.0

Description

This check can be used to ensure that types are not declared to be thrown. Declaring that a method throws java.lang.Error or java.lang.RuntimeException is almost never acceptable.

Properties

name description type default value since
illegalClassNames Specify throw class names to reject. String Set java.lang.Throwable, RuntimeException, Error, Throwable, java.lang.Error, java.lang.RuntimeException 4.0
ignoredMethodNames Specify names of methods to ignore. String Set finalize 5.4
ignoreOverriddenMethods allow to ignore checking overridden methods (marked with Override or java.lang.Override annotation). Boolean true 6.4

Examples

To configure the check:

<module name="IllegalThrows"/>
        

To configure the check rejecting throws NullPointerException from methods:

<module name="IllegalThrows">
  <property name="illegalClassNames" value="NullPointerException"/>
</module>
        

To configure the check ignoring method named "foo()":

<module name="IllegalThrows">
  <property name="ignoredMethodNames" value="foo"/>
</module>
        

To configure the check to warn on overridden methods:

<module name="IllegalThrows">
  <property name="ignoreOverriddenMethods" value="false"/>
</module>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

IllegalToken

Since Checkstyle 3.2

Description

Checks for illegal tokens. By default labels are prohibited.

Rationale: Certain language features can harm readability, lead to confusion or are not obvious to novice developers. Other features may be discouraged in certain frameworks, such as not having native methods in Enterprise JavaBeans components.

Properties

name description type default value since
tokens tokens to check subset of tokens TokenTypes. LABELED_STAT. 3.2

Examples

To configure the check:

<module name="IllegalToken"/>
        

To configure the check to find token LITERAL_NATIVE:

<module name="IllegalToken">
  <property name="tokens" value="LITERAL_NATIVE"/>
</module>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

IllegalTokenText

Since Checkstyle 3.2

Description

Checks specified tokens text for matching an illegal pattern from format property. By default no tokens are specified.

Properties

name description type default value since
format Define the RegExp for illegal pattern. Regular Expression "^$" (empty) 3.2
ignoreCase Control whether to ignore case when matching. Boolean false 3.2
message Define the message which is used to notify about violations; if empty then the default message is used. String "" 3.2
tokens tokens to check subset of tokens NUM_DOUBLE, NUM_FLOAT, NUM_INT, NUM_LONG, IDENT, COMMENT_CONTENT, STRING_LITERAL, CHAR_LITERAL. empty 3.2

Examples

To configure the check to forbid String literals containing "a href":

<module name="IllegalTokenText">
  <property name="tokens" value="STRING_LITERAL"/>
  <property name="format" value="a href"/>
</module>
        

To configure the check to forbid leading zeros in an integer literal, other than zero and a hex literal:

<module name="IllegalTokenText">
  <property name="tokens" value="NUM_INT,NUM_LONG"/>
  <property name="format" value="^0[^lx]"/>
  <property name="ignoreCase" value="true"/>
</module>
        

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

IllegalType

Since Checkstyle 3.2

Description

Checks that particular classes or interfaces are never used.

Rationale: Helps reduce coupling on concrete classes.

For additional restriction of type usage see also: IllegalInstantiation, IllegalImport

Properties

name description type default value since
validateAbstractClassNames Control whether to validate abstract class names. Boolean false 6.10
illegalClassNames Specify classes that should not be used as types in variable declarations, return values or parameters. String Set LinkedHashSet, java.util.HashSet, java.util.LinkedHashMap, java.util.TreeMap, HashMap, TreeSet, java.util.HashMap, TreeMap, java.util.LinkedHashSet, java.util.TreeSet, HashSet, LinkedHashMap 3.2
legalAbstractClassNames Define abstract classes that may be used as types. String Set {} 4.2
ignoredMethodNames Specify methods that should not be checked. String Set getInitialContext, getEnvironment 3.2
illegalAbstractClassNameFormat Specify RegExp for illegal abstract class names. Regular Expression "^(.*[.])?Abstract.*$" 3.2
memberModifiers Control whether to check only methods and fields with any of the specified modifiers. This property does not affect method calls nor method references. subset of tokens TokenTypes no tokens 6.3
tokens tokens to check subset of tokens ANNOTATION_FIELD_DEF, CLASS_DEF, INTERFACE_DEF, METHOD_CALL, METHOD_DEF, METHOD_REF, PARAMETER_DEF, VARIABLE_DEF. ANNOTATION_FIELD_DEF, CLASS_DEF, INTERFACE_DEF, METHOD_CALL, METHOD_DEF, METHOD_REF, PARAMETER_DEF, VARIABLE_DEF. 3.2

Notes

It is possible to set illegal class names via short or canonical name. Specifying illegal type invokes analyzing imports and Check puts violations at corresponding declarations (of variables, methods or parameters). This helps to avoid ambiguous cases, e.g.: java.awt.List was set as illegal class name, then, code like:

import java.util.List;
...
List list; //No violation here
        

will be ok.

In most cases it's justified to put following classes to illegalClassNames:

  • GregorianCalendar
  • Hashtable
  • ArrayList
  • LinkedList
  • Vector

as methods that are differ from interface methods are rarely used, so in most cases user will benefit from checking for them.

Examples

To configure the check so that it ignores getInstance() methods:

<module name="IllegalType">
  <property name="ignoredMethodNames" value="getInstance"/>
</module>
        

To configure the Check so that it verifies only public, protected or static methods and fields:

<module name="IllegalType">
  <property name="memberModifiers" value="LITERAL_PUBLIC,
   LITERAL_PROTECTED, LITERAL_STATIC"/>
</module>
        

To configure the check so that it verifies usage of types Boolean and Foo:

<module name="IllegalType">
          <property name="illegalClassNames" value="Boolean, Foo"/>
</module>
        
public class Test {

  public Set<Boolean> set; // violation
  public java.util.List<Map<Boolean, Foo>> list; // violation

  private void method(List<Foo> list, Boolean value) { // violation
    SomeType.<Boolean>foo(); // violation
    final Consumer<Foo> consumer = Foo<Boolean>::foo; // violation
  }

  public <T extends Boolean, U extends Serializable> void typeParam(T a) {} // violation

  public void fullName(java.util.ArrayList<? super Boolean> a) {} // violation

  public abstract Set<Boolean> shortName(Set<? super Boolean> a); // violation

  public Set<? extends Foo> typeArgument() { // violation
    return new TreeSet<Foo<Boolean>>();
  }

}
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

InnerAssignment

Since Checkstyle 3.0

Description

Checks for assignments in subexpressions, such as in String s = Integer.toString(i = 2);.

Rationale: With the exception of for iterators and assignment in while idiom, all assignments should occur in their own top-level statement to increase readability. With inner assignments like the one given above, it is difficult to see all places where a variable is set.

Note: Check allows usage of the popular assignment in while idiom:

String line;
while ((line = bufferedReader.readLine()) != null) {
  // process the line
}
        

Assignment inside a condition is not a problem here, as the assignment is surrounded by an extra pair of parentheses. The comparison is != null and there is no chance that intention was to write line == reader.readLine().

Examples

To configure the check:

<module name="InnerAssignment"/>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

MagicNumber

Since Checkstyle 3.1

Description

Checks that there are no "magic numbers" where a magic number is a numeric literal that is not defined as a constant. By default, -1, 0, 1, and 2 are not considered to be magic numbers.

Constant definition is any variable/field that has 'final' modifier. It is fine to have one constant defining multiple numeric literals within one expression:

static final int SECONDS_PER_DAY = 24 * 60 * 60;
static final double SPECIAL_RATIO = 4.0 / 3.0;
static final double SPECIAL_SUM = 1 + Math.E;
static final double SPECIAL_DIFFERENCE = 4 - Math.PI;
static final Border STANDARD_BORDER = BorderFactory.createEmptyBorder(3, 3, 3, 3);
static final Integer ANSWER_TO_THE_ULTIMATE_QUESTION_OF_LIFE = new Integer(42);
        

Properties

name description type default value since
ignoreNumbers Specify non-magic numbers. Number Set -1, 0, 1, 2 3.1
ignoreHashCodeMethod Ignore magic numbers in hashCode methods. Boolean false 5.3
ignoreAnnotation Ignore magic numbers in annotation declarations. Boolean false 5.4
ignoreFieldDeclaration Ignore magic numbers in field declarations. Boolean false 6.6
constantWaiverParentToken Specify tokens that are allowed in the AST path from the number literal to the enclosing constant definition. subset of tokens TokenTypes TYPECAST, METHOD_CALL, EXPR, ARRAY_INIT, UNARY_MINUS, UNARY_PLUS, ELIST, STAR, ASSIGN, PLUS, MINUS, DIV, LITERAL_NEW 6.11
tokens tokens to check subset of tokens NUM_DOUBLE, NUM_FLOAT, NUM_INT, NUM_LONG. NUM_DOUBLE, NUM_FLOAT, NUM_INT, NUM_LONG. 3.1

Examples

To configure the check with default configuration:

<module name="MagicNumber"/>
        

results is following violations:

@MyAnnotation(6) // violation
class MyClass {
  private field = 7; // violation

  void foo() {
    int i = i + 1; // no violation
    int j = j + 8; // violation
  }
}
        

To configure the check so that it checks floating-point numbers that are not 0, 0.5, or 1:

<module name="MagicNumber">
  <property name="tokens" value="NUM_DOUBLE, NUM_FLOAT"/>
  <property name="ignoreNumbers" value="0, 0.5, 1"/>
  <property name="ignoreFieldDeclaration" value="true"/>
  <property name="ignoreAnnotation" value="true"/>
</module>
        

results is following violations:

@MyAnnotation(6) // no violation
class MyClass {
  private field = 7; // no violation

  void foo() {
    int i = i + 1; // no violation
    int j = j + 8; // violation
  }
}
        

Config example of constantWaiverParentToken option:

<module name="MagicNumber">
  <property name="constantWaiverParentToken" value="ASSIGN,ARRAY_INIT,EXPR,
  UNARY_PLUS, UNARY_MINUS, TYPECAST, ELIST, DIV, PLUS "/>
</module>
        

result is following violation:

class TestMethodCall {
  public void method2() {
    final TestMethodCall dummyObject = new TestMethodCall(62);    //violation
    final int a = 3;        // ok as waiver is ASSIGN
    final int [] b = {4, 5} // ok as waiver is ARRAY_INIT
    final int c = -3;       // ok as waiver is UNARY_MINUS
    final int d = +4;       // ok as waiver is UNARY_PLUS
    final int e = method(1, 2) // ELIST is there but violation due to METHOD_CALL
    final int x = 3 * 4;    // violation
    final int y = 3 / 4;    // ok as waiver is DIV
    final int z = 3 + 4;    // ok as waiver is PLUS
    final int w = 3 - 4;    // violation
    final int x = (int)(3.4);    //ok as waiver is TYPECAST
  }
}
       

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

MissingCtor

Since Checkstyle 3.4

Description

Checks that classes (except abstract ones) define a constructor and don't rely on the default one.

Examples

To configure the check:

<module name="MissingCtor"/>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

MissingSwitchDefault

Since Checkstyle 3.1

Description

Checks that switch statement has a "default" clause.

Rationale: It's usually a good idea to introduce a default case in every switch statement. Even if the developer is sure that all currently possible cases are covered, this should be expressed in the default branch, e.g. by using an assertion. This way the code is protected against later changes, e.g. introduction of new types in an enumeration type.

Examples

To configure the check:

<module name="MissingSwitchDefault"/>
        

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

ModifiedControlVariable

Since Checkstyle 3.5

Description

Check for ensuring that for loop control variables are not modified inside the for block. An example is:

for (int i = 0; i < 1; i++) {
  i++; //violation
}
        

Rationale: If the control variable is modified inside the loop body, the program flow becomes more difficult to follow. See FOR statement specification for more details.

Such loop would be suppressed:

for (int i = 0; i < 10;) {
  i++;
}
        

Properties

name description type default value since
skipEnhancedForLoopVariable Control whether to check enhanced for-loop variable. Boolean false 6.8

Examples

To configure the check:

<module name="ModifiedControlVariable"/>
        

By default, This Check validates Enhanced For-Loop.

Option 'skipEnhancedForLoopVariable' could be used to skip check of variable from Enhanced For Loop.

An example of how to configure the check so that it skips enhanced For Loop Variable is:

<module name="ModifiedControlVariable">
  <property name="skipEnhancedForLoopVariable" value="true"/>
</module>
         

Example:

for (String line: lines) {
  line = line.trim();   // it will skip this violation
}
         

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

MultipleStringLiterals

Since Checkstyle 3.5

Description

Checks for multiple occurrences of the same string literal within a single file.

Rationale: Code duplication makes maintenance more difficult, so it can be better to replace the multiple occurrences with a constant.

Properties

name description type default value since
allowedDuplicates Specify the maximum number of occurrences to allow without generating a warning. Integer 1 3.5
ignoreStringsRegexp Specify RegExp for ignored strings (with quotation marks). Regular Expression "^""$" 4.0
ignoreOccurrenceContext Specify token type names where duplicate strings are ignored even if they don't match ignoredStringsRegexp. This allows you to exclude syntactical contexts like annotations or static initializers from the check. subset of tokens TokenTypes ANNOTATION 4.4

Examples

To configure the check:

<module name="MultipleStringLiterals"/>
        

To configure the check so that it allows two occurrences of each string:

<module name="MultipleStringLiterals">
  <property name="allowedDuplicates" value="2"/>
</module>
        

To configure the check so that it ignores ", " and empty strings:

<module name="MultipleStringLiterals">
  <property name="ignoreStringsRegexp"
    value='^(("")|(", "))$'/>
</module>
        

To configure the check so that it flags duplicate strings in all syntactical contexts, even in annotations like @SuppressWarnings("unchecked"):

<module name="MultipleStringLiterals">
  <property name="ignoreOccurrenceContext" value=""/>
</module>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

MultipleVariableDeclarations

Since Checkstyle 3.4

Description

Checks that each variable declaration is in its own statement and on its own line.

Rationale: the Java code conventions chapter 6.1 recommends that declarations should be one per line/statement.

Examples

To configure the check:

<module name="MultipleVariableDeclarations"/>
        

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

NestedForDepth

Since Checkstyle 5.3

Description

Restricts nested for blocks to a specified depth (default = 1).

Properties

name description type default value since
max Specify maximum allowed nesting depth. Integer 1 5.3

Examples

To configure the check:

<module name="NestedForDepth"/>
        

To configure the check to allow nesting depth 3:

<module name="NestedForDepth">
  <property name="max" value="3"/>
</module>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

NestedIfDepth

Since Checkstyle 3.2

Description

Restricts nested if-else blocks to a specified depth (default = 1).

Properties

name description type default value since
max Specify maximum allowed nesting depth. Integer 1 3.2

Examples

To configure the check:

<module name="NestedIfDepth"/>
        

To configure the check to allow nesting depth 3:

<module name="NestedIfDepth">
  <property name="max" value="3"/>
</module>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

NestedTryDepth

Since Checkstyle 3.2

Description

Restricts nested try blocks to a specified depth (default = 1).

Properties

name description type default value since
max Specify maximum allowed nesting depth. Integer 1 3.2

Examples

To configure the check:

<module name="NestedTryDepth"/>
        

To configure the check to allow nesting depth 3:

<module name="NestedTryDepth">
  <property name="max" value="3"/>
</module>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

NoClone

Since Checkstyle 5.0

Description

Checks that the clone method is not overridden from the Object class.

This check is almost exactly the same as the NoFinalizerCheck.

See Object.clone()

Rationale: The clone method relies on strange, hard to follow rules that are difficult to get right and do not work in all situations. In some cases, either a copy constructor or a static factory method can be used instead of the clone method to return copies of an object. For more information on rules for the clone method and its issues, see Effective Java: Programming Language Guide First Edition by Joshua Bloch pages 45-52.

Below are some of the rules/reasons why the clone method should be avoided.

  • Classes supporting the clone method should implement the Cloneable interface but the Cloneable interface does not include the clone method. As a result, it doesn't enforce the method override.
  • The Cloneable interface forces the Object's clone method to work correctly. Without implementing it, the Object's clone method will throw a CloneNotSupportedException.
  • Non-final classes must return the object returned from a call to super.clone().
  • Final classes can use a constructor to create a clone which is different from non-final classes.
  • If a super class implements the clone method incorrectly all subclasses calling super.clone() are doomed to failure.
  • If a class has references to mutable objects then those object references must be replaced with copies in the clone method after calling super.clone().
  • The clone method does not work correctly with final mutable object references because final references cannot be reassigned.
  • If a super class overrides the clone method then all subclasses must provide a correct clone implementation.

Two alternatives to the clone method, in some cases, is a copy constructor or a static factory method to return copies of an object. Both of these approaches are simpler and do not conflict with final fields. They do not force the calling client to handle a CloneNotSupportedException. They also are typed therefore no casting is necessary. Finally, they are more flexible since they can take interface types rather than concrete classes.

Sometimes a copy constructor or static factory is not an acceptable alternative to the clone method. The example below highlights the limitation of a copy constructor (or static factory). Assume Square is a subclass for Shape.

Shape s1 = new Square();
System.out.println(s1 instanceof Square); //true
        

...assume at this point the code knows nothing of s1 being a Square that's the beauty of polymorphism but the code wants to copy the Square which is declared as a Shape, its super type...

Shape s2 = new Shape(s1); //using the copy constructor
System.out.println(s2 instanceof Square); //false
        

The working solution (without knowing about all subclasses and doing many casts) is to do the following (assuming correct clone implementation).

Shape s2 = s1.clone();
System.out.println(s2 instanceof Square); //true
        

Just keep in mind if this type of polymorphic cloning is required then a properly implemented clone method may be the best choice.

Much of this information was taken from Effective Java: Programming Language Guide First Edition by Joshua Bloch pages 45-52. Give Bloch credit for writing an excellent book.

Examples

To configure the check:

<module name="NoClone"/>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

NoFinalizer

Since Checkstyle 5.0

Description

Verifies there are no finalize() methods defined in a class.

See Object.finalize()

Rationale: Finalizers are unpredictable, often dangerous, and generally unnecessary. Their use can cause erratic behavior, poor performance, and portability problems. For more information for the finalize method and its issues, see Effective Java: Programming Language Guide Third Edition by Joshua Bloch, §8.

Examples

To configure the check:

<module name="NoFinalizer"/>
        

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

OneStatementPerLine

Since Checkstyle 5.3

Description

Checks that there is only one statement per line.

Rationale: It's very difficult to read multiple statements on one line.

In the Java programming language, statements are the fundamental unit of execution. All statements except blocks are terminated by a semicolon. Blocks are denoted by open and close curly braces.

OneStatementPerLineCheck checks the following types of statements: variable declaration statements, empty statements, import statements, assignment statements, expression statements, increment statements, object creation statements, 'for loop' statements, 'break' statements, 'continue' statements, 'return' statements, resources statements.

Examples

The following examples will be flagged as a violation:

//Each line causes violation:
int var1; int var2;
var1 = 1; var2 = 2;
int var1 = 1; int var2 = 2;
var1++; var2++;
Object obj1 = new Object(); Object obj2 = new Object();
import java.io.EOFException; import java.io.BufferedReader;
;; //two empty statements on the same line.

//Multi-line statements:
int var1 = 1
; var2 = 2; //violation here
int o = 1, p = 2,
r = 5; int t; //violation here
          

Note: resource declarations can contain variable definitions and variable references (from java9). This check is only applied to variable definitions. If there are one or more variable references and one variable definition on the same line in resources declaration, there is no violation. The following examples will illustrate difference:

OutputStream s1 = new PipedOutputStream();
OutputStream s2 = new PipedOutputStream();
// only one statement(variable definition) with two variable references
try (s1; s2; OutputStream s3 = new PipedOutputStream();) // OK
{}
// two statements with variable definitions
try (Reader r = new PipedReader(); s2; Reader s3 = new PipedReader() // violation
) {}
         

An example of how to configure this Check:

<module name="OneStatementPerLine"/>
        

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

OverloadMethodsDeclarationOrder

Since Checkstyle 5.8

Description

Checks that overload methods are grouped together.

Examples

Example of incorrect grouping overload methods:

public void foo(int i) {}
public void foo(String s) {}
public void notFoo() {} // Have to be after foo(int i, String s)
public void foo(int i, String s) {}
        

An example of how to configure the check is:

<module name="OverloadMethodsDeclarationOrder"/>
        

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

PackageDeclaration

Since Checkstyle 3.2

Description

Ensures that a class has a package declaration, and (optionally) whether the package name matches the directory name for the source file.

Rationale: Classes that live in the null package cannot be imported. Many novice developers are not aware of this.

Packages provide logical namespace to classes and should be stored in the form of directory levels to provide physical grouping to your classes. These directories are added to the classpath so that your classes are visible to JVM when it runs the code.

Properties

name description type default value since
matchDirectoryStructure Control whether to check for directory and package name match. Boolean true 7.6.1

Examples

To configure the check:

<module name="PackageDeclaration"/>
        

Let us consider the class AnnotationLocationCheck which is in the directory /com/puppycrawl/tools/checkstyle/checks/annotations/

package com.puppycrawl.tools.checkstyle.checks; //Violation
public class AnnotationLocationCheck extends AbstractCheck {
  //...
}
        

Example of how the check works when matchDirectoryStructure option is set to false. Let us again consider the AnnotationLocationCheck class located at directory /com/puppycrawl/tools/checkstyle/checks/annotations/ along with the following setup,

<module name="PackageDeclaration">
<property name="matchDirectoryStructure" value="false"/>
</module>
        
package com.puppycrawl.tools.checkstyle.checks;  //No Violation

public class AnnotationLocationCheck extends AbstractCheck {
  //...
}
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

ParameterAssignment

Since Checkstyle 3.2

Description

Disallows assignment of parameters.

Rationale: Parameter assignment is often considered poor programming practice. Forcing developers to declare parameters as final is often onerous. Having a check ensure that parameters are never assigned would give the best of both worlds.

Examples

To configure the check:

<module name="ParameterAssignment"/>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

RequireThis

Since Checkstyle 3.4

Description

Checks that references to instance variables and methods of the present object are explicitly of the form "this.varName" or "this.methodName(args)" and that those references don't rely on the default behavior when "this." is absent.

Warning: the Check is very controversial if 'validateOnlyOverlapping' option is set to 'false' and not that actual nowadays.

Rationale:

  1. The same notation/habit for C++ and Java (C++ have global methods, so having "this." do make sense in it to distinguish call of method of class instead of global).
  2. Non-IDE development (ease of refactoring, some clearness to distinguish static and non-static methods).

Notes

Limitations: Nothing is currently done about static variables or catch-blocks. Static methods invoked on a class name seem to be OK; both the class name and the method name have a DOT parent. Non-static methods invoked on either this or a variable name seem to be OK, likewise.

Properties

name description type default value since
checkFields Control whether to check references to fields. Boolean true 3.4
checkMethods Control whether to check references to methods. Boolean true 3.4
validateOnlyOverlapping Control whether to check only overlapping by variables or arguments. Boolean true 6.17

Examples

To configure the default check:

<module name="RequireThis"/>
        

To configure to check the this qualifier for fields only:

<module name="RequireThis">
  <property name="checkMethods" value="false"/>
</module>
        

Examples of how the check works if validateOnlyOverlapping option is set to true:

public static class A {
  private int field1;
  private int field2;

  public A(int field1) {
    // Overlapping by constructor argument.
    field1 = field1; // violation: Reference to instance variable "field1" needs "this".
    field2 = 0;
  }

  void foo3() {
    String field1 = "values";
    // Overlapping by local variable.
    field1 = field1; // violation:  Reference to instance variable "field1" needs "this".
  }
}

public static class B {
  private int field;

  public A(int f) {
    field = f;
  }

  String addSuffixToField(String field) {
    // Overlapping by method argument. Equal to "return field = field + "suffix";"
    return field += "suffix"; // violation: Reference to instance variable "field" needs "this".
  }
}
       

Please, be aware of the following logic, which is implemented in the check:

1) If you arrange 'this' in your code on your own, the check will not raise violation for variables which use 'this' to reference a class field, for example:

public class C {
  private int scale;
  private int x;
  public void foo(int scale) {
    scale = this.scale; // no violation
    if (scale > 0) {
      scale = -scale; // no violation
    }
    x *= scale;
  }
}
       

2) If method parameter is returned from the method, the check will not raise violation for returned variable/parameter, for example:

public class D {
  private String prefix;
  public String modifyPrefix(String prefix) {
    prefix = "^" + prefix + "$" // no violation (modification of parameter)
    return prefix; // modified method parameter is returned from the method
  }
}
       

Examples of how the check works if validateOnlyOverlapping option is set to false:

public static class A {
  private int field1;
  private int field2;

  public A(int field1) {
    field1 = field1; // violation: Reference to instance variable "field1" needs "this".
    field2 = 0; // violation: Reference to instance variable "field2" needs "this".
    String field2;
    field2 = "0"; // No violation. Local var allowed
  }

  void foo3() {
    String field1 = "values";
    field1 = field1; // violation:  Reference to instance variable "field1" needs "this".
  }
}

public static class B {
  private int field;

  public A(int f) {
    field = f; // violation:  Reference to instance variable "field" needs "this".
  }

  String addSuffixToField(String field) {
    return field += "suffix"; // violation: Reference to instance variable "field" needs "this".
  }
}

// If the variable is locally defined, there won't be a violation provided the variable
// doesn't overlap.
class C {
  private String s1 = "foo1";
  String s2 = "foo2";

  C() {
    s1 = "bar1"; // Violation. Reference to instance variable 's1' needs "this.".
    String s2;
    s2 = "bar2"; // No violation. Local var allowed.
    s2 += s2; // Violation. Overlapping. Reference to instance variable 's2' needs "this.".
  }
}
       

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

ReturnCount

Since Checkstyle 3.2

Description

Restricts the number of return statements in methods, constructors and lambda expressions (2 by default). Ignores specified methods (equals() by default).

max property will only check returns in methods and lambdas that return a specific value (Ex: 'return 1;').

maxForVoid property will only check returns in methods, constructors, and lambdas that have no return type (IE 'return;'). It will only count visible return statements. Return statements not normally written, but implied, at the end of the method/constructor definition will not be taken into account. To disallow "return;" in void return type methods, use a value of 0.

Rationale: Too many return points can mean that code is attempting to do too much or may be difficult to understand.

Properties

name description type default value since
max Specify maximum allowed number of return statements in non-void methods/lambdas. Integer 2 3.2
maxForVoid Specify maximum allowed number of return statements in void methods/constructors/lambdas. Integer 1 6.19
format Specify method names to ignore. Regular Expression "^equals$" 3.4
tokens tokens to check subset of tokens CTOR_DEF, METHOD_DEF, LAMBDA. CTOR_DEF, METHOD_DEF, LAMBDA. 3.2

Examples

To configure the check so that it doesn't allow more than three return statements per method (ignoring the equals() method):

<module name="ReturnCount">
  <property name="max" value="3"/>
</module>
        

To configure the check so that it doesn't allow any return statements per void method:

<module name="ReturnCount">
  <property name="maxForVoid" value="0"/>
</module>
        

To configure the check so that it doesn't allow more than 2 return statements per method (ignoring the equals() method) and more than 1 return statements per void method:

<module name="ReturnCount">
  <property name="max" value="2"/>
  <property name="maxForVoid" value="1"/>
</module>
        

To configure the check so that it doesn't allow more than three return statements per method for all methods:

<module name="ReturnCount">
  <property name="max" value="3"/>
  <property name="format" value="^$"/>
</module>
        

To configure the check so that it doesn't allow any return statements in constructors, more than one return statement in all lambda expressions and more than two return statements in methods:

<module name="ReturnCount">
  <property name="max" value="0"/>
  <property name="tokens" value="CTOR_DEF"/>
</module>
<module name="ReturnCount">
  <property name="max" value="1"/>
  <property name="tokens" value="LAMBDA"/>
</module>
<module name="ReturnCount">
  <property name="max" value="2"/>
  <property name="tokens" value="METHOD_DEF"/>
</module>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

SimplifyBooleanExpression

Since Checkstyle 3.0

Description

Checks for over-complicated boolean expressions. Currently finds code like if (b == true), b || true, !false, etc.

Rationale: Complex boolean logic makes code hard to understand and maintain.

Examples

To configure the check:

<module name="SimplifyBooleanExpression"/>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

SimplifyBooleanReturn

Since Checkstyle 3.0

Description

Checks for over-complicated boolean return statements. For example the following code

if (valid())
  return false;
else
  return true;
        

could be written as

return !valid();
        

The idea for this Check has been shamelessly stolen from the equivalent PMD rule.

Examples

To configure the check:

<module name="SimplifyBooleanReturn"/>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

StringLiteralEquality

Since Checkstyle 3.2

Description

Checks that string literals are not used with == or !=.

Rationale: Novice Java programmers often use code like:

if (x == "something")
        

when they mean

if ("something".equals(x))
        

Examples

To configure the check:

<module name="StringLiteralEquality"/>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

SuperClone

Since Checkstyle 3.2

Description

Checks that an overriding clone() method invokes super.clone(). Does not check native methods, as they have no possible java defined implementation.

Reference: Object.clone().

Examples

To configure the check:

<module name="SuperClone"/>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

SuperFinalize

Since Checkstyle 3.2

Description

Checks that an overriding finalize() method invokes super.finalize(). Does not check native methods, as they have no possible java defined implementation.

References: How to Handle Java Finalization's Memory-Retention Issues; 10 points on finalize method in Java.

Examples

To configure the check:

<module name="SuperFinalize"/>
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

UnnecessaryParentheses

Since Checkstyle 3.4

Description

Checks if unnecessary parentheses are used in a statement or expression. The check will flag the following with warnings:

    return (x);          // parens around identifier
    return (x + 1);      // parens around return value
    int x = (y / 2 + 1); // parens around assignment rhs
    for (int i = (0); i < 10; i++) {  // parens around literal
    t -= (z + 1);        // parens around assignment rhs
        

Notes

The check is not "type aware", that is to say, it can't tell if parentheses are unnecessary based on the types in an expression. It also doesn't know about operator precedence and associativity; therefore it won't catch something like

            int x = (a + b) + c;
        

In the above case, given that a,b, and c are all int variables, the parentheses around a + b are not needed.

Examples

To configure the check:

<module name="UnnecessaryParentheses"/>
        

Example of Usage

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

UnnecessarySemicolonInEnumeration

Since Checkstyle 8.22

Description

Checks if unnecessary semicolon is in enum definitions. Semicolon is not needed if enum body contains only enum constants.

Examples

To configure the check:

<module name="UnnecessarySemicolonInEnumeration"/>
        

Example of violations

enum One {
    A,B; // violation
}
enum Two {
    A,B,; // violation
}
enum Three {
    A,B(); // violation
}
enum Four {
    A,B{}; // violation
}
enum Five {
    A,
    B
    ; // violation
}
        

Example of good cases

enum Normal {
    A,
    B,
    ; // required ";", no violation
    Normal(){}
}
enum NoSemicolon {
    A, B // only enum constants, no semicolon required
}
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

UnnecessarySemicolonInTryWithResources

Since Checkstyle 8.22

Description

Checks if unnecessary semicolon is used in last resource declaration.

Properties

name description type default value since
allowWhenNoBraceAfterSemicolon Allow unnecessary semicolon if closing paren is not on the same line. Boolean true 8.22

Examples

To configure the check:

<module name="UnnecessarySemicolonInTryWithResources"/>
        

Example of violations

class A {
    void method() throws IOException {
        try(Reader r1 = new PipedReader();){} // violation
        try(Reader r4 = new PipedReader();Reader r5 = new PipedReader()
        ;){} // violation
        try(Reader r6 = new PipedReader();
            Reader r7
                   = new PipedReader();
        ){}
    }
}
        

To configure the check to detect unnecessary semicolon if closing paren is not on same line

<module name="UnnecessarySemicolonInTryWithResources">
  <property name="allowWhenNoBraceAfterSemicolon" value="false"/>
</module>
        

Example of exclusion

class A {
    void method() throws IOException {
        try(Reader r1 = new PipedReader();){} // violation
        try(Reader r6 = new PipedReader();
            Reader r7 = new PipedReader(); // violation
        ){}
    }
}
        

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker

VariableDeclarationUsageDistance

Since Checkstyle 5.8

Description

Checks the distance between declaration of variable and its first usage.

Properties

name description type default value since
allowedDistance Specify distance between declaration of variable and its first usage. Values should be greater than 0. Integer 3 5.8
ignoreVariablePattern Define RegExp to ignore distance calculation for variables listed in this pattern. Regular Expression "" 5.8
validateBetweenScopes Allow to calculate the distance between declaration of variable and its first usage in the different scopes. Boolean false 5.8
ignoreFinal Allow to ignore variables with a 'final' modifier. Boolean true 5.8

Examples

Example #1:

int count;
a = a + b;
b = a + a;
count = b; // DECLARATION OF VARIABLE 'count'
           // SHOULD BE HERE (distance = 3)
        

Example #2:

int count;
{
  a = a + b;
  count = b; // DECLARATION OF VARIABLE 'count'
             // SHOULD BE HERE (distance = 2)
}
        

Check can detect a block of initialization methods. If a variable is used in such a block and there is no other statements after this variable then distance=1.

Case #1:

int minutes = 5;
Calendar cal = Calendar.getInstance();
cal.setTimeInMillis(timeNow);
cal.set(Calendar.SECOND, 0);
cal.set(Calendar.MILLISECOND, 0);
cal.set(Calendar.HOUR_OF_DAY, hh);
cal.set(Calendar.MINUTE, minutes);
        

The distance for the variable minutes is 1 even though this variable is used in the fifth method's call.

Case #2:

int minutes = 5;
Calendar cal = Calendar.getInstance();
cal.setTimeInMillis(timeNow);
cal.set(Calendar.SECOND, 0);
cal.set(Calendar.MILLISECOND, 0);
System.out.println(cal);
cal.set(Calendar.HOUR_OF_DAY, hh);
cal.set(Calendar.MINUTE, minutes);
         

The distance for the variable minutes is 6 because there is one more expression (except the initialization block) between the declaration of this variable and its usage.

An example how to configure this Check:

<module name="VariableDeclarationUsageDistance"/>
         

An example of how to configure this Check: - to set the allowed distance to 4; - to ignore variables with prefix '^temp'; - to force the validation between scopes; - to check the final variables;

<module name="VariableDeclarationUsageDistance">
  <property name="allowedDistance" value="4"/>
  <property name="ignoreVariablePattern" value="^temp.*"/>
  <property name="validateBetweenScopes" value="true"/>
  <property name="ignoreFinal" value="false"/>
</module>
         

Notes

ATTENTION!! (Not supported cases)

Case #1:
{
  int c;
  int a = 3;
  int b = 2;
    {
      a = a + b;
      c = b;
    }
}
        

Distance for variable 'a' = 1; Distance for variable 'b' = 1; Distance for variable 'c' = 2.

As distance by default is 1 the Check doesn't raise warning for variables 'a' and 'b' to move them into the block.

Case #2:

int sum = 0;
for (int i = 0; i < 20; i++) {
  a++;
  b--;
  sum++;
  if (sum > 10) {
    res = true;
  }
}
         

Distance for variable 'sum' = 3.

As the distance is more than the default one, the Check raises warning for variable 'sum' to move it into the 'for(...)' block. But there is situation when variable 'sum' hasn't to be 0 within each iteration. So, to avoid such warnings you can use Suppression Filter, provided by Checkstyle, for the whole class.

Error Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.coding

Parent Module

TreeWalker