除非附近有评论，否则 checkstyle 不允许 SuppressWarnings 注释

Question

在我们的项目中，有时我们不得不抑制一些警告（例如 "WeakerAccess" 可能会被抑制，因为项目也被用作另一个项目中的库，或者 "expression is always false" 对于 instanceof 从库中抛出的已检查异常，掩盖了抛出该异常的事实）。

另一方面，仅仅添加一个抑制是不好的，因为它可能不清楚为什么会在那里。所以，我想添加一个 checkstyler 规则，如果附近有评论，它只允许 SuppressWarnings 注释。这应该足以让人们开始添加解释。

但我找不到办法做到这一点。有这个块：

<module name="SuppressWarnings">
  <property name="format"
      value="^unchecked$|^unused$"/>
  <property name="tokens"
    value="
    CLASS_DEF,INTERFACE_DEF,ENUM_DEF,
    ANNOTATION_DEF,ANNOTATION_FIELD_DEF,
    ENUM_CONSTANT_DEF,METHOD_DEF,CTOR_DEF
    "/>
</module>

还有一些关于关闭一行的 checkstyler 的特殊注释的东西，但这只是另一个需要解释的抑制警告的东西......但是有没有办法说抑制是可以的，如果有附近有评论吗（在前一行或同一行）？

Answer 1

我建议同时使用 2 个检查。使用 SuppressWarningsCheck to flag the methods you want documented and display an error message that says it is a violation because it is not documented. Then use SuppressWithNearbyCommentFilter 来抑制添加文档时违反其他检查的情况。要使过滤器正常工作，文档必须以特定文本开头，这样它就不会错误地抑制实际上没有文档的 SuppressWarnings。

示例：

$ cat TestClass.java
public class TestClass {
    //SuppressWarnings: this is my reason for the suppression
    @SuppressWarnings("unchecked")
    void method() {
    }

    //this is just a comment and not a reason
    @SuppressWarnings("unused")
    void method2() {
    }

    @SuppressWarnings("unused")
    void noComment() {
    }
}

$ cat TestConfig.xml
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
          "-//Puppy Crawl//DTD Check Configuration 1.3//EN"
          "http://www.puppycrawl.com/dtds/configuration_1_3.dtd">

<module name="Checker">
    <property name="charset" value="UTF-8"/>

    <module name="TreeWalker">
    <module name="SuppressWarnings">
        <property name="format" value="^(unchecked|unused)$"/>
        <message key="suppressed.warning.not.allowed"
             value="The warning ''{0}'' cannot be suppressed at this location unless a comment is given for the reason for the suppression." />
        <property name="tokens" value="CLASS_DEF,INTERFACE_DEF,ENUM_DEF,ANNOTATION_DEF,ANNOTATION_FIELD_DEF,ENUM_CONSTANT_DEF,METHOD_DEF,CTOR_DEF"/>
    </module>
    <module name="SuppressWithNearbyCommentFilter">
      <property name="commentFormat"
                value="SuppressWarnings: .{10,}"/>
      <property name="checkFormat" value="SuppressWarnings"/>
      <property name="influenceFormat" value="3"/>
    </module>
    </module>
</module>

$ java -jar checkstyle-8.18-all.jar -c TestConfig.xml TestClass.java
Starting audit...
[ERROR] TestClass.java:8:23: The warning 'unused' cannot be suppressed at this location unless a comment is given for the reason for the suppression. [SuppressWarnings]
[ERROR] TestClass.java:12:23: The warning 'unused' cannot be suppressed at this location unless a comment is given for the reason for the suppression. [SuppressWarnings]
Audit done.
Checkstyle ends with 2 errors.

您会注意到有 2 次违规，但有 3 次 SuppressWarnings。第一个示例展示了如何正确抑制没有文档。第 2 个只显示评论但不显示有关抑制的文档，第 3 个根本不显示任何评论。

<property name="format" value="^(unchecked|unused)$"/>

这指定只有未经检查和未使用的抑制需要文档。如果您想要除这两种类型之外的所有类型的文档，我建议使用表达式 "^((?!unchecked|unused).)*$".

除非附近有评论，否则 checkstyle 不允许 SuppressWarnings 注释

checkstyle disallow SuppressWarnings annotation unless there is a comment nearby

checkstyle

suppress-warnings

maven-checkstyle-plugin