CommentsIndentation

Since Checkstyle 6.10

Description

Controls the indentation between comments and surrounding code. Comments are indented at the same level as the surrounding code. Detailed info about such convention can be found here

Properties

name description type default value since
tokens tokens to check subset of tokens SINGLE_LINE_COMMENT , BLOCK_COMMENT_BEGIN . SINGLE_LINE_COMMENT , BLOCK_COMMENT_BEGIN . 6.10

Examples

To configure the Check where both single-line and block comments are checked for indentation violations: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="CommentsIndentation"/>
  </module>
</module>

Example: 

public class Example1 {
  void testMethod() {
    /*
     * it is Ok
     */
    boolean bool = true;
      // violation below, 'Block comment has incorrect indentation level 6'
      /*
       * It is not okay
       */
    double d = 3.14;
  }

  public void foo1() {
    foo2();
    // it is OK
  }

  public void foo2() {
    int i;
        // It is not okay
  }
  // violation 2 lines above  'Comment has incorrect indentation level 8'
}

To configure the Check to validate only single-line comments: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="CommentsIndentation">
      <property name="tokens" value="SINGLE_LINE_COMMENT"/>
    </module>
  </module>
</module>

Example: 

public class Example2 {
  void testMethod() {
    /*
     * it is Ok
     */
    boolean bool = true;

      /*
       * It is not okay
       */
    double d = 3.14;
  }

  public void foo1() {
    foo2();
    // it is OK
  }

  public void foo2() {
    int i;
        // It is not okay
  }
  // violation 2 lines above  'Comment has incorrect indentation level 8'
}

Please take a look at the following examples to understand how the check works:

Example #3: Comment is used as a single-line border to separate groups of methods. 

public class Example3 {
  /////////////////////////////// it is OK

  public void foo1() {
    int a = 0;
  }
    ///////////////////////////// It is not okay

  // violation 2 lines above 'Comment has incorrect indentation level 4'
  public void foo2() {}
}

Example #4: Single line block comment is placed within an empty code block. Note, if comment is placed at the end of the empty code block, we have Checkstyle's limitations to clearly detect user intention of explanation target - above or below. The only case we can assume as a violation is when a single-line comment within the empty code block has indentation level that is lower than the indentation level of the closing right curly brace. 

public class Example4 {
  public void foo1() {
    // comment
    // block
    // it is OK (we cannot clearly detect user intention of explanation target)
  }
  // violation 4 lines below 'Comment has incorrect indentation level 1'
  public void foo2() {
 // comment
 // block
 // It is not okay
  }
}

Example #5: 'fallthrough' comments and Also similar comments placed within an empty case block.Note, if comment is placed at the end of the empty case block, we have Checkstyle limitations to clearly detect user intention of explanation target - above or below. The only case we can assume as a violation is when a single-line comment within the empty case block has indentation level that is lower than the indentation level of the next case. token.

public class Example5 {
  void testMethod(String a) {
    switch(a) {
      case "1":
        int j = 7;
        // it is OK
        break;
      case "3": // violation 2 lines below 'Comment has incorrect indentation level'
        if (true) {}
            //It is not okay
        break;
      // fall through (it is OK)
      case "5":
        // it is OK
      case "6":
     // It is not okay
      case "7":
       // violation 2 lines above 'Comment has incorrect indentation level 5'
      default:
    }
  }
}

Example #6: Comment is placed within a distributed statement.

public class Example6 {
  void testMethod() {
    // violation 2 lines below 'Comment has incorrect indentation level 4'
    String breaks = "J"
    // It is not okay
        + "A"
        // it is OK
        + "V"
        + "A"
    // it is OK
    ;

  }
}

Example #7: Single line block comment has previous and next statement. 

public class Example7 {
  void testMethod() {
    String s1 = "Clean code!";
    s1.toString().toString().toString();
    // single-line
    // block
    // comment (it is OK)
    int a = 5;

    String s2 = "Code complete!";
    s1.toString().toString().toString();
              // It is not okay1
         //It is not okay2
       //It is not okay3
    int b = 18;
    // violation 4 lines above 'Comment has incorrect indentation level 14'
    // violation 4 lines above 'Comment has incorrect indentation level 9'
    // violation 4 lines above 'Comment has incorrect indentation level 7'
  }
}

Example #8: Comment within the block tries to describe the next code block. 

public class Example8 {
  public void foo42() {
    int a = 5;
    if (a == 5) {
      int b;
      // it is OK
    } else if (a ==6) {}
  }

  public void foo43() {
    // violation 3 lines below 'Comment has incorrect indentation level 5'
    try {
      int a;
     // It is not okay
    } catch (Exception e) {  }
  }
}

Example of Usage

Violation 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.indentation

Parent Module

TreeWalker