Description

Rationale: Same as SuppressionCommentFilter. Whereas the SuppressionCommentFilter uses matched pairs of filters to turn on/off comment matching, SuppressWithNearbyCommentFilter uses single comments. This requires fewer lines to mark a region, and may be aesthetically preferable in some contexts.

Attention: This filter may only be specified within the TreeWalker module (<module name="TreeWalker"/>) and only applies to checks which are also defined within this module. To filter non-TreeWalker checks like RegexpSingleline, a SuppressWithPlainTextCommentFilter or similar filter must be used.

Notes

SuppressWithNearbyCommentFilter can suppress Checks that have Treewalker as parent module.

Properties

Examples

To configure a filter to suppress audit events for check on any line with a comment SUPPRESS CHECKSTYLE check:

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressWithNearbyCommentFilter"/>
    <module name="NoWhitespaceAfter"/>
  </module>
</module>
        

Example:

public class Example1 {
  private int [] array; // SUPPRESS CHECKSTYLE NoWhitespaceAfter
}
        

To configure a filter to suppress all audit events on any line containing the comment CHECKSTYLE IGNORE THIS LINE:

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressWithNearbyCommentFilter">
      <property name="commentFormat" value="CHECKSTYLE IGNORE THIS LINE"/>
      <property name="checkFormat" value=".*"/>
      <property name="influenceFormat" value="0"/>
    </module>
    <module name="ConstantName"/>
  </module>
</module>
        

Example:

public class Example2 {
  public static final int lowerCaseConstant = 1; // CHECKSTYLE IGNORE THIS LINE
}
        

To configure a filter so that // OK to catch (Throwable|Exception|RuntimeException) here permits the current and previous line to avoid generating an IllegalCatch audit event:

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressWithNearbyCommentFilter">
      <property name="commentFormat" value="OK to catch (\w+) here"/>
      <property name="checkFormat" value="IllegalCatchCheck"/>
      <property name="messageFormat" value="$1"/>
      <property name="influenceFormat" value="-1"/>
    </module>
    <module name="IllegalCatch"/>
  </module>
</module>
        

Example:

public class Example3 {
  public void doStuff() {
    try {
      // blah blah blah
    }
    catch(RuntimeException re) {
      // OK to catch RuntimeException here
    }
  }
}
        

To configure a filter so that CHECKSTYLE IGNORE check FOR NEXTvar LINES avoids triggering any audits for the given check for the current line and the next var lines (for a total of var+1 lines):

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressWithNearbyCommentFilter">
      <property name="commentFormat"
          value="CHECKSTYLE IGNORE (\w+) FOR NEXT (\d+) LINES"/>
      <property name="checkFormat" value="$1"/>
      <property name="influenceFormat" value="$2"/>
    </module>
    <module name="ConstantName"/>
  </module>
</module>
        

Example:

public class Example4 {
  // CHECKSTYLE IGNORE ConstantNameCheck FOR NEXT 4 LINES
  static final int lowerCaseConstant1 = 1;
  static final int lowerCaseConstant2 = 2;
  static final int lowerCaseConstant3 = 3;
  static final int lowerCaseConstant4 = 4;
  static final int lowerCaseConstant5 = 5; // violation 'must match pattern'
}
        

To configure a filter to avoid any audits on code like:

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressWithNearbyCommentFilter">
      <property name="commentFormat"
                value="ALLOW (\w+) ON PREVIOUS LINE"/>
      <property name="influenceFormat" value="-1"/>
    </module>
    <module name="MemberName"/>
  </module>
</module>
        

Example:

public class Example5 {
  private int D2;
  // ALLOW MemberName ON PREVIOUS LINE
}
        

To configure a filter to allow suppress one or more Checks (separated by "|") and demand comment no less than 14 symbols:

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressWithNearbyCommentFilter">
      <property name="commentFormat"
                value="@cs\.suppress \[(\w+(\|\w+)*)\] \w[-\.'`,:;\w ]{13,}"/>
      <property name="checkFormat" value="$1"/>
      <property name="influenceFormat" value="1"/>
    </module>
    <module name="ConstantName"/>
    <module name="NoWhitespaceAfter"/>
  </module>
</module>
        

Example:

public class Example6 {
  // @cs.suppress [ConstantName|NoWhitespaceAfter] A comment here
  public static final int [] array = {};
}
        

It is possible to specify an ID of checks, so that it can be leveraged by the SuppressWithNearbyCommentFilter to skip validations. The following examples show how to skip validations near code that has comment like // @cs-: <ID/> (reason), where ID is the ID of checks you want to suppress.

Example of Checkstyle checks and SuppressWithNearbyCommentFilter configuration (idFormat which is set to '$1' points that ID of the checks is in the first group of commentFormat regular expressions):

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressWithNearbyCommentFilter">
      <property name="commentFormat"
        value="@cs\.suppress \[(\w+(\|\w+)*)\] \w[-\.'`,:;\w ]{14,}"/>
      <property name="checkFormat" value="$1"/>
      <property name="influenceFormat" value="1"/>
    </module>
    <module name="RegexpSinglelineJava">
      <property name="id" value="ignore"/>
      <property name="format" value="^.*@Ignore\s*$"/>
      <property name="message" value="@Ignore should have a reason."/>
    </module>
    <module name="RegexpSinglelineJava">
      <property name="id" value="systemout"/>
      <property name="format" value="^.*System\.\(out|err\).*$"/>
      <property name="message" value="Don't use System.out/err, use SLF4J instead."/>
    </module>
  </module>
</module>
        

Example:

public class Example7 {
  @Ignore // @cs-: ignore (test has not been implemented yet)
  @Test
  public void testMethod() {}

  public static void foo() {

    System.out.println("Debug info."); // @cs-: systemout (should not fail)
  }
}
        

Example of how to configure the check to suppress more than one checks. The influence format is specified in the second regexp group.

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressWithNearbyCommentFilter">
      <property name="commentFormat" value="@cs-\: ([\w\|]+) influence (\d+)"/>
      <property name="checkFormat" value="$1"/>
      <property name="influenceFormat" value="$2"/>
    </module>
    <module name="ClassDataAbstractionCoupling">
      <property name="max" value="1" />
    </module>
    <module name="MagicNumber"/>
  </module>
</module>
        

Example:

// @cs-: ClassDataAbstractionCoupling influence 2
// @cs-: MagicNumber influence 4
public class Example8 { // no violations from ClassDataAbstractionCoupling here
  private Example1 foo = new Example1();
  private Example2 bar = new Example2();
  private int value = 10022; // no violations from MagicNumber here
}
        

Example of Usage

• Checkstyle Style
• Google Style

Package

com.puppycrawl.tools.checkstyle.filters

Parent Module

TreeWalker