Checkstyle ignores to be defined in source code

Hi devs,

Right now when we want to delay fixing checkstyle errors (not good, but sometimes it’s needed temporarily…) or if there are false positives (I don’t think we have that with checkstyle, do we?), we use a checkstyle-suppressions.xml file.

For example:

<!DOCTYPE suppressions PUBLIC
    "-//Puppy Crawl//DTD Suppressions 1.0//EN"
    "http://www.puppycrawl.com/dtds/suppressions_1_0.dtd">

<suppressions>
  <suppress checks="BooleanExpressionComplexity" files="Base64BinaryStringEncoder.java" lines="59-60"/>
  <suppress checks="BooleanExpressionComplexity" files="HexBinaryStringEncoder.java" lines="58-59"/>
  <suppress checks="BooleanExpressionComplexity" files="UrlBase64BinaryStringEncoder" lines="46-47"/>
</suppressions>

After discussing with other devs on matrix, I’d like to propose that we change this practice to use exclusions inside the source files themselves and drop the usage of checkstyle-suppressions.xml files.

Here are the rules I’m proposing:

• If the issue affects the whole class/interface/etc, use @SuppressWarnings("checkstyle:<rule name here>") on the class/interface/etc

• If the issue affects a whole method, use @SuppressWarnings("checkstyle:<rule name here>") on the method

• If the issue affects a variable declaration, use @SuppressWarnings("checkstyle:<rule name here>") on the variable declaration

• If the issue affects a line (basically whenever an annotation is not allowed), use // CHECKSTYLE IGNORE <rule name> or // CHECKSTYLE IGNORE <rule name> FOR <n> LINES.

  Example:

    @Override
    InternalBinaryStringEncoder getEncoder()
    {
        return new AbstractBouncyCastleInternalBinaryStringEncoder(new HexEncoder(), BLOCK_SIZE, CHAR_SIZE)
        {
            @Override
            public boolean isValidEncoding(byte b)
            {
                // CHECKSTYLE IGNORE BooleanExpressionComplexity
                return ((b >= 0x2f && b <= 0x39) || (b >= 0x41 && b <= 0x46) || (b >= 0x61 && b <= 0x66));
            }
        };
    }
  

This proposal would be a must for new code and a best effort to fix existing excludes and move from the file usage to the code usage.

WDYT?

Thanks

PS1: I’ll later propose something for SonarCloud too.
PS2: We can configure the wording for the comment excludes. For now I’ve configured checkstyle with:

    <module name="SuppressWithNearbyCommentFilter">
      <property name="commentFormat" value="CHECKSTYLE IGNORE (\w+)"/>
      <property name="checkFormat" value="$1"/>
      <property name="influenceFormat" value="1"/>
    </module>

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

10 posts - 5 participants

Read full topic