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

Posted 2023-02-21

【中文标题】Checkstyle 警告 Eclipse “Javadoc 标记之前应该有一个空行”，即使有一个

【英文标题】：Checkstyle Warning Eclipse "Javadoc tag should be preceded with an empty line" even though there is one

【发布时间】：2021-11-27 20:06:39

【问题描述】：

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

例如：

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

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

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

感谢您的帮助！

【问题讨论】：

任何帮助/想法/建议将不胜感激

如果有不清楚的地方，请告诉我，以便我编辑问题

这些问题***.com/questions/5077382/… ***.com/questions/55144437/… 不幸没有帮助我

【参考方案1】：

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

但最重要的是......

您的流程已损坏。您有一个样式检查器，而您现在专注于完全不相关的事情，但您的 javadoc 很糟糕。

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

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

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

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

如果您确实要添加一些内容，但描述它返回的内容完全涵盖了它，那么 只需 编写 @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%，而且还没有四舍五入。

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

【讨论】：

这不应该是一个公认的答案。仅仅因为您认为“可能……”某些字节以某种方式存在，而 CheckStyle“可能……”以某种方式实现并不能做到这一点。答案应与参考文献或证明示例或反例一起记录。最后，这是 Stack Overflow 而不是 StackExchange 代码审查，因此其余的答案是无关紧要的，而且长度对任何未来的问题和答案读者都特别无益。