Checkstyle 警告 Eclipse “Javadoc 标记前应该有一个空行”，即使有一个

Question

我在 Eclipse 中使用 Checkstyle（Google Checks），并且对于每个 Javadoc 标记，编译器都会显示警告“Javadoc 标记应该以空行开头”，即使有一个。 消除警告的唯一方法是引入 HTML 断线应答器。

例如：

     /**
   * shows drinks units in fridge.
   * 
   * @return amount of drinks in fridge.
   */

编译器将给出警告“Javadoc 标记 '@return' 应该以空行开头”。

当然可以在 Checkstyle 中停用警告，但是我仍然想知道编译器为什么会这样做。 即使没有换行应答器，我的老师和同学也没有那个警告，他们不知道为什么我有它，并且在 Checkstyle 的 sourceforge 页面上（ https://checkstyle.sourceforge.io/apidocs/com/puppycrawl/ tools/checkstyle/checks/javadoc/RequireEmptyLineBeforeBlockTagGroupCheck.html )、HTML 应答器也不是必需的。

谢谢你的帮助 ！

Answer 1

我意识到这是因为当您按 Enter 时 Eclipse 会在星号后自动插入一个空格（如果您要在该行上写一些东西，这很有意义），但当您再次按 Enter 时不会删除它。 因此，Javadoc 标记之前的行实际上是： <leading indentation>*<space> 。 手动删除此空间会为我删除 Checkstyle 警告。

也许其他人知道如何配置 Eclipse 以自动删除这个空间。 就个人而言，我坚持使用Google 的 XML 格式化程序配置文件，因为他们的google-java-format Eclipse 插件不起作用（未处理的异常）。 也许 google-java-format 可以解决这个问题。

Answer 2

我的解决方案是
使用正则表达式搜索\* $ ，并将所有替换为* 。

Answer 3

我发现如果我突出显示有问题的 javadoc 和格式代码 (Ctrl-Alt-L)，intelliJ 会解决这个问题

Answer 4

这也发生在 NetBeans (12.6) 中。 似乎很常见。 我发现，如果您删除以*开头的行的选项，问题就会消失。 例如如下图：

/**
 JavaDoc Summary.

 @since 1.0.0
 @author javafueled
 */

我通常不喜欢这种格式，所以我必须记住修复线条。 @since ;) NetBeans 没有提供自动更正它的方法。

Answer 5

检查该位置的确切字节。 上面可能有一个实际的字符，例如不间断空格； 文字处理器通常会“喜欢”您的输入并将它们变成奇怪的字符。 例如，如果您将“hello”粘贴到 word 中，然后再粘贴回 java，则它不再是字符串常量，因为 word 决定将它们变成花引号：“hello”不是 java。 可以使用相同的策略在其中潜入不间断的空间等。 绝大多数空白 unicode 字符都算作空格，但 checkstyle 插件在这方面可能会被破坏（它只会认为空格和制表符不相关）。 或者，checkstyle 可能需要在空行上的 * 之后有一个空格，以便该行上的完整字符集是\t * （制表符、空格、星号、空格）。

但最重要的是...

你的过程被打破了。 你有一个样式检查器，你现在专注于一些完全不相关的东西，但是你的 javadoc 很糟糕。

您有一个可能名为countDrinksInFridge()的方法，并且您使用 javadoc“记录”了此方法，该方法为您提供了完全无用的非信息，并执行了两次以启动！ DRY是编程中几乎普遍同意的奇妙原则，而您只是违反了它，这是有原因的。 两次，不少于。

样式检查器抱怨您使用了哪种确切的空格字符，但认为编写愚蠢的 javadoc 是完美的，这一事实应该足以证明它显然没有做它应该做的事情。

好的文档规则如下。 它们都基于一个简单的想法：文档应该被维护，维护不是免费的，并且文档很难甚至不可能测试，因此它们中的任何错误往往会在人们意识到它错误之前徘徊很长时间。 就像在编写代码时一样，如果您不必要地花费 10 行代码来编写本可以在 2 中同样有效地完成的代码，那么您就搞砸了。 这同样适用于文档。 不要重复自己，不要提供无意义或多余的信息。 说清楚，说清楚。

• 如果由于方法名称准确地描述了方法的整个性质而没有其他要添加的内容，请不要记录它。 方法名称是文档。 让它独立存在。

• 如果您确实要添加一些内容，但描述它返回的内容完全涵盖了它，那么只需编写@return标记。 这可以：

/**
 * @return amount of drinks in the fridge.
 */
public int countDrinks() { ... ... }

您在这里拥有 javadoc 的唯一原因是有人认为提及“在冰箱中”是值得的。 当然，这仍然是不好的代码风格：

class Fridge {
    /**
     * @return The amount of drinks in the fridge.
     */
    public int countDrinks() { ...... }
}

这很糟糕，因为“在冰箱里”在这里不是有用的信息。 呃，当然是在冰箱里。 它在一个名为Fridge的类中。 想一想：给我一个程序员对Fridge的countDrinks方法的作用感到困惑的可能性，但是 javadoc @return The amount of drinks in the fridge. 为他们清除了一切。 当然，这些几率是 0%，甚至没有四舍五入。

教训是：防止糟糕的代码风格、难以维护的代码以及其他类似风格指南的想法的过程是您无法仅使用软件和规则包来解决的问题。 这是人类的事：你从事团队内培训、招聘实践、代码审查流程、一种应该关心代码的客观质量的一般文化，而不是陷入过度强制的测量，例如“代码库是否通过”一些风格检查器规则集？'，只有在你建立了所有这些之后，你才能考虑使用一些软件来轻松地帮助你完成团队的需求。