Skip to content

Google style: Disallow comments enclosed in boxes #17697

@VeniceWish

Description

@VeniceWish

I have read check documentation: https://checkstyle.sourceforge.io/checks/misc/todocomment.html
I have downloaded the latest checkstyle from: https://checkstyle.org/cmdline.html#Download_and_Run
I have executed the cli and showed it below, as cli describes the problem better than 1,000 words

From: https://google.github.io/styleguide/javaguide.html#s4.8.6-comments

Comments are not enclosed in boxes drawn with asterisks or other characters.

Code:

/*
  #################################
  #      Illegal Comment1         #
  #################################
*/
class Test {
  /**********************************
   *      Illegal Comment2          *
   **********************************/
  void doSomething(int x) {
    int y = x + 2;
    // -------------------
    //      comment
    // -------------------
  }

  // ======== separator ========
  void func() {}

  // ######
}

Cli:

$ java -jar checkstyle-10.26.1-all.jar -c google_checks.xml Test.java 
Starting audit...
[WARN] Test.java:7: First sentence of Javadoc is missing an ending period. [SummaryJavadoc]
Audit done.

Formatter:

$ java -jar google-java-format-1.28.0-all-deps.jar Test.java > FormattedCode.java
$ diff -Naru Test.java FormattedCode.java
None

We need a new check to enforce that comments are not enclosed in boxes drawn with asterisks or other characters, as required by the Google Java Style Guide §4.8.6.
Currently, Checkstyle provides TodoComment, which can be configured with a regex like:

<module name="Checker">
  <module name="TreeWalker">
    <module name="TodoComment">
      <property name="format" value="(?m)^\s*([*=_#-])\1{5,}\s*$"/>
    </module>
  </module>
</module>

Output:

$ java -jar checkstyle-10.26.1-all.jar -c config.xml Test.java
Starting audit...
[ERROR] Test.java:1:3: Comment matches to-do format '(?m)^\s*([*=_#-])\1{5,}\s*$'. [TodoComment]
[ERROR] Test.java:7:5: Comment matches to-do format '(?m)^\s*([*=_#-])\1{5,}\s*$'. [TodoComment]
[ERROR] Test.java:12:7: Comment matches to-do format '(?m)^\s*([*=_#-])\1{5,}\s*$'. [TodoComment]
[ERROR] Test.java:14:7: Comment matches to-do format '(?m)^\s*([*=_#-])\1{5,}\s*$'. [TodoComment]
[ERROR] Test.java:20:5: Comment matches to-do format '(?m)^\s*([*=_#-])\1{5,}\s*$'. [TodoComment]
Audit done.
Checkstyle ends with 5 errors.

This produces a similar effect, but TodoComment can only detect lines that match a regex.
It cannot determine whether those lines actually enclose a comment block.
As a result, even a single separator line like // ###### is flagged as a violation.
Note: Whether a single-line separator such as // ###### should be considered a violation is debatable — this ultimately depends on the design decision of the new check.


Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions