SuppressWithPlainTextCommentFilter

Since Checkstyle 8.6

Description

Filter SuppressWithPlainTextCommentFilter uses plain text to suppress audit events. The filter can be used only to suppress audit events received from the checks which implement FileSetCheck interface. In other words, the checks which have Checker as a parent module. The filter knows nothing about AST, it treats only plain text comments and extracts the information required for suppression from the plain text comments. Currently, the filter supports only single-line comments.

Please, be aware of the fact that, it is not recommended to use the filter for Java code anymore, however you still are able to use it to suppress audit events received from the checks which implement FileSetCheck interface.

Rationale: Sometimes there are legitimate reasons for violating a check. When this is a matter of the code in question and not personal preference, the best place to override the policy is in the code itself. Semi-structured comments can be associated with the check. This is sometimes superior to a separate suppressions file, which must be kept up-to-date as the source file is edited.

Note that the suppression comment should be put before the violation. You can use more than one suppression comment each on separate line.

Properties

name description type default value since
checkFormat Specify check pattern to suppress. Pattern ".*" 8.6
idFormat Specify check ID pattern to suppress. Pattern null 8.24
messageFormat Specify message pattern to suppress. Pattern null 8.6
offCommentFormat Specify comment pattern to trigger filter to begin suppression. Pattern "// CHECKSTYLE:OFF" 8.6
onCommentFormat Specify comment pattern to trigger filter to end suppression. Pattern "// CHECKSTYLE:ON" 8.6

Notes

Properties offCommentFormat and onCommentFormat must have equal paren counts.

SuppressionWithPlainTextCommentFilter can suppress Checks that have Treewalker or Checker as parent module.

Examples

To configure a filter to suppress audit events between a comment containing CHECKSTYLE:OFF and a comment containing CHECKSTYLE:ON: 

<module name="Checker">
  <module name="SuppressWithPlainTextCommentFilter"/>
</module>

To configure a filter to suppress audit events between a comment containing line BEGIN GENERATED CONTENT and a comment containing line END GENERATED CONTENT (Checker is configured to check only properties files): 

<module name="Checker">
  <property name="fileExtensions" value="properties"/>

  <module name="SuppressWithPlainTextCommentFilter">
    <property name="offCommentFormat" value="BEGIN GENERATED CONTENT"/>
    <property name="onCommentFormat" value="END GENERATED CONTENT"/>
  </module>

</module>

Example:

//BEGIN GENERATED CONTENT
my.property=value1 // No violation events will be reported
my.property=value2 // No violation events will be reported
//END GENERATED CONTENT
. . .

To configure a filter so that -- stop tab check and -- resume tab check marks allowed tab positions (Checker is configured to check only sql files): 

<module name="Checker">
  <property name="fileExtensions" value="sql"/>

  <module name="SuppressWithPlainTextCommentFilter">
    <property name="offCommentFormat" value="stop tab check"/>
    <property name="onCommentFormat" value="resume tab check"/>
    <property name="checkFormat" value="FileTabCharacterCheck"/>
  </module>

</module>

Example:

-- stop tab check
  SELECT * FROM users // won't warn here if there is a tab character on line
-- resume tab check
  SELECT 1 // will warn here if there is a tab character on line

To configure a filter so that name of suppressed check mentioned in comment CSOFF: regexp and CSON: regexp mark a matching check (Checker is configured to check only xml files): 

<module name="Checker">
  <property name="fileExtensions" value="xml"/>

  <module name="SuppressWithPlainTextCommentFilter">
    <property name="offCommentFormat" value="CSOFF\: ([\w\|]+)"/>
    <property name="onCommentFormat" value="CSON\: ([\w\|]+)"/>
    <property name="checkFormat" value="$1"/>
  </module>

</module>

Example:

// CSOFF: RegexpSinglelineCheck
 // RegexpSingleline check won't warn any lines below here if the line matches regexp
<condition property="checkstyle.ant.skip">
  <isset property="checkstyle.ant.skip"/>
</condition>
// CSON: RegexpSinglelineCheck
// RegexpSingleline check will warn below here if the line matches regexp
<property name="checkstyle.pattern.todo" value="NOTHingWillMatCH_-"/>

To configure a filter to suppress all audit events between a comment containing CHECKSTYLE_OFF: ALMOST_ALL and a comment containing CHECKSTYLE_OFF: ALMOST_ALL except for the EqualsHashCode check (Checker is configured to check only java files): 

<module name="Checker">
  <property name="fileExtensions" value="java"/>

  <module name="SuppressWithPlainTextCommentFilter">
    <property name="offCommentFormat"
      value="CHECKSTYLE_OFF: ALMOST_ALL"/>
    <property name="onCommentFormat"
      value="CHECKSTYLE_ON: ALMOST_ALL"/>
    <property name="checkFormat"
      value="^((?!(FileTabCharacterCheck)).)*$"/>
  </module>

</module>

Example:

// CHECKSTYLE_OFF: ALMOST_ALL
public static final int array [];
private String [] strArray;
// CHECKSTYLE_ON: ALMOST_ALL
private int array1 [];

To configure a filter to suppress Check's violation message which matches specified message in messageFormat (so suppression will not be only by Check's name, but also by message text, as the same Check can report violations with different message format) between a comment containing stop and comment containing resume: 

<module name="Checker">
  <module name="SuppressWithPlainTextCommentFilter">
    <property name="offCommentFormat" value="stop"/>
    <property name="onCommentFormat" value="resume"/>
    <property name="checkFormat" value="FileTabCharacterCheck"/>
    <property name="messageFormat"
        value="^File contains tab characters (this is the first instance)\.$"/>
  </module>
</module>

It is possible to specify an ID of checks, so that it can be leveraged by the SuppressWithPlainTextCommentFilter to skip validations. The following examples show how to skip validations near code that is surrounded with -- CSOFF <ID> (reason) and -- CSON <ID>, where ID is the ID of checks you want to suppress.

Example of Checkstyle checks and SuppressWithPlainTextCommentFilter configuration (checkFormat which is set to '$1' points that ID of the checks is in the first group of offCommentFormat and onCommentFormat regular expressions): 

<module name="Checker">
  <property name="fileExtensions" value="sql"/>

  <module name="SuppressWithPlainTextCommentFilter">
    <property name="offCommentFormat" value="CSOFF (\w+) \(\w+\)"/>
    <property name="onCommentFormat" value="CSON (\w+)"/>
    <property name="idFormat" value="$1"/>
  </module>

  <module name="TreeWalker">
    <module name="RegexpSinglelineJava">
      <property name="id" value="count"/>
      <property name="format" value="^.*COUNT(*).*$"/>
      <property name="message"
        value="Don't use COUNT(*), use COUNT(1) instead."/>
    </module>

    <module name="RegexpSinglelineJava">
      <property name="id" value="join"/>
      <property name="format" value="^.*JOIN\s.+\s(ON|USING)$"/>
      <property name="message"
        value="Don't use JOIN, use sub-select instead."/>
    </module>
  </module>

</module>

Example:

-- CSOFF join (it is ok to use join here for performance reasons)
SELECT name, job_name
FROM users AS u
JOIN jobs AS j ON u.job_id = j.id
-- CSON join

-- CSOFF count (test query execution plan)
EXPLAIN SELECT COUNT(*) FROM restaurants
-- CSON count

Example of how to configure the check to suppress more than one check (Checker is configured to check only sql files). 

<module name="Checker">
  <property name="fileExtensions" value="sql"/>

  <module name="SuppressWithPlainTextCommentFilter">
    <property name="offCommentFormat" value="@cs-\: ([\w\|]+)"/>
    <property name="checkFormat" value="$1"/>
  </module>

</module>

Example:

-- @cs-: RegexpSinglelineCheck
-- @cs-: FileTabCharacterCheck
CREATE TABLE STATION (
  ID INTEGER PRIMARY KEY,
  CITY CHAR(20),
  STATE CHAR(2),
  LAT_N REAL,
  LONG_W REAL);

This check is not limited to comments. It can match any text in the given file as offCommentFormat and onCommentFormat for the suppression. The following example shows how to suppress violations within a text block for LineLength. 

<module name="Checker">
  <module name="LineLength">
      <property name="max" value="100"/>
  </module>
  <module name="SuppressWithPlainTextCommentFilter">
    <property name="offCommentFormat" value='=\s+"""'/>
    <property name="onCommentFormat" value='^\s+""";'/>
  </module>
</module>

Example:

public class Example9 {

  // ok, opening and closing triple quotes are 'offCommentFormat' and 'onCommentFormat'
  static final String LOCATION_CSV_SAMPLE = """
          locationId,label,regionId,regionLabel,vendorId,vendorLabel,address,address2,city,stateProvinceCode,zipCode,countryCode,latitude,longitude
          ST001,Station 001,ZONE1,Zone 1,CP1,Competitor 1,123 Street,Unit 2,Houston,TX,77033,US,29.761496813335178,-95.53049214204984
          ST002,Station 002,ZONE2,,CP2,,668 Street,Unit 23,San Jose,CA,95191,US,37.35102477242508,-121.9209934020318
          """;

  // violation below, 'Line is longer than 80 characters'
  static final String SINGLE_LINE_SAMPLE = "locationId,label,regionId,regionLabel,vendorId,vendorLabel,address,address2,city,stateProvinceCode,zipCode,countryCode,latitude,longitude";
}

Example of Usage

Package

com.puppycrawl.tools.checkstyle.filters

Parent Module

Checker