Checkstyle Warning Eclipse "Javadoc tag should be preceded with an empty line" 即使有一个
Checkstyle Warning Eclipse "Javadoc tag should be preceded with an empty line" even though there is one
我在 Eclipse 中使用 Checkstyle (Google Checks)，对于每个 Javadoc 标记，编译器都会显示警告“Javadoc 标记前面应该有一个空行”，即使有一个。消除警告的唯一方法是引入一个 HTML 换行应答器。
例如：
/**
* shows drinks units in fridge.
*
* @return amount of drinks in fridge.
*/
编译器会给出警告“Javadoc 标签‘@return’前面应该有一个空行”。
当然可以在 Checkstyle 中取消激活警告，但是我仍然想知道为什么编译器会那样做。即使没有换行应答器，我的老师和同学也没有那个警告，他们不知道为什么我有它，在 Checkstyle (https://checkstyle.sourceforge.io/apidocs/com/puppycrawl/tools/checkstyle/checks/javadoc/RequireEmptyLineBeforeBlockTagGroupCheck.html) 的 sourceforge 页面上，HTML 应答器也没有必填。
感谢您的帮助！
检查该位置的确切字节数。上面可能有一个真实的字符，比如一个不间断的-space；文字处理器通常 'fancy up' 你的输入并将它们变成奇怪的字符。例如，如果您将“hello”粘贴到 word 中，然后再粘贴回 java，它就不再是字符串常量，因为 word 决定将它们变成弯引号：“hello”，这不是 java。同样的策略可以用来在里面偷偷使用不间断的 spaces 之类的东西。绝大多数空白 unicode 字符算作白色 space，但 checkstyle 插件在这方面可能会被破坏（它只会将 space 和制表符视为无关紧要）。或者，checkstyle 可能是 requiring 一个 space 在空行上的 * 之后，以便该行上的完整字符集是 \t * （制表符，space, 星级, space).
但最重要的是...
你的进程坏了。你有一个风格检查器，你现在专注于一些完全不相关的东西，但是你的java文档很糟糕。
您有一个可能名为 countDrinksInFridge() 的方法，并且您 'documented' 这个方法和 javadoc 给了您完全无用的非信息，并且执行了两次，以启动！ DRY 是编程中几乎普遍认同的绝妙原则，这是有原因的，而您却违反了它。两次，不少于
样式检查器抱怨您使用了哪种 space 字符，但认为编写愚蠢的 javadoc 是完美的，这一事实应该足以证明它显然没有这样做它应该是什么。
好的文档规则如下。它们都基于一个简单的想法：文档应该维护，维护不是免费的，而且文档很难甚至不可能测试，所以它们中的任何错误往往会在人们意识到错误之前徘徊很长时间。就像在编写代码时一样，如果您不必要地花费 10 行来编写本可以在 2 中同样有效地完成的代码，那么您就搞砸了。这同样适用于文档。不要重复自己，不要提供无意义或多余的信息。说清楚，说简洁。
如果因为方法名称准确地描述了方法的全部性质而没有什么要补充的，那么不要记录它。方法名是文档。让它自立。
如果您确实有要添加的内容，但描述的内容 returns 完全涵盖了它，那么 只需 写下 @return 标签.这很好：
/**
* @return amount of drinks in the fridge.
*/
public int countDrinks() { ... ... }
你在这里有 javadoc 的唯一原因是因为有人认为提及 'in the fridge' 是值得的。当然，这仍然是糟糕的代码风格：
class Fridge {
/**
* @return The amount of drinks in the fridge.
*/
public int countDrinks() { ...... }
}
这很糟糕，因为 'in the fridge' 在这里不是有用的信息。呃，当然在冰箱里。它位于名为 Fridge 的 class 中。想一想：程序员可能对 Fridge 的 countDrinks 方法的作用感到困惑，但 javadoc @return The amount of drinks in the fridge. 为他们澄清了一切。当然，这些几率是 0%，而且还没有四舍五入。
教训是：防止不良代码风格、难以维护代码和其他类似风格指南的流程是您无法仅用软件和规则包解决的问题。这是人类的事：你致力于团队内培训、招聘实践、代码审查流程，以及一种普遍的文化，人们应该关心代码的 objective 质量，而不是挂在过度强制的测量上，例如 'does the codebase pass some style-checker ruleset?'，只有当你所有这些都建立起来之后，你才能考虑得到一些软件来轻松地帮助你完成团队的需求。
我意识到这是因为 Eclipse 会在您按回车键时自动在星号后插入一个 space（如果您要在线上写东西，这是有意义的）但不会在您按下时删除它再次按回车。所以 Javadoc 标记之前的行实际上是：<leading indentation>*<space>。删除此 space 会为我手动删除 Checkstyle 警告。
也许其他人知道如何配置 Eclipse 以自动删除此 space。就个人而言，我坚持使用 Google's XML formatter profile because their google-java-format Eclipse plugin 不起作用（未处理的异常）。也许 google-java-format 会解决这个问题。
我的解决方案是
使用正则表达式搜索 \* $，然后将所有内容替换为 *.
我在 Eclipse 中使用 Checkstyle (Google Checks)，对于每个 Javadoc 标记，编译器都会显示警告“Javadoc 标记前面应该有一个空行”，即使有一个。消除警告的唯一方法是引入一个 HTML 换行应答器。
例如：
/**
* shows drinks units in fridge.
*
* @return amount of drinks in fridge.
*/
编译器会给出警告“Javadoc 标签‘@return’前面应该有一个空行”。
当然可以在 Checkstyle 中取消激活警告，但是我仍然想知道为什么编译器会那样做。即使没有换行应答器，我的老师和同学也没有那个警告，他们不知道为什么我有它，在 Checkstyle (https://checkstyle.sourceforge.io/apidocs/com/puppycrawl/tools/checkstyle/checks/javadoc/RequireEmptyLineBeforeBlockTagGroupCheck.html) 的 sourceforge 页面上，HTML 应答器也没有必填。
感谢您的帮助！
检查该位置的确切字节数。上面可能有一个真实的字符，比如一个不间断的-space；文字处理器通常 'fancy up' 你的输入并将它们变成奇怪的字符。例如，如果您将“hello”粘贴到 word 中，然后再粘贴回 java，它就不再是字符串常量，因为 word 决定将它们变成弯引号：“hello”，这不是 java。同样的策略可以用来在里面偷偷使用不间断的 spaces 之类的东西。绝大多数空白 unicode 字符算作白色 space，但 checkstyle 插件在这方面可能会被破坏（它只会将 space 和制表符视为无关紧要）。或者，checkstyle 可能是 requiring 一个 space 在空行上的 * 之后，以便该行上的完整字符集是 \t * （制表符，space, 星级, space).
但最重要的是...
你的进程坏了。你有一个风格检查器，你现在专注于一些完全不相关的东西，但是你的java文档很糟糕。
您有一个可能名为 countDrinksInFridge() 的方法，并且您 'documented' 这个方法和 javadoc 给了您完全无用的非信息，并且执行了两次，以启动！ DRY 是编程中几乎普遍认同的绝妙原则，这是有原因的，而您却违反了它。两次，不少于
样式检查器抱怨您使用了哪种 space 字符，但认为编写愚蠢的 javadoc 是完美的，这一事实应该足以证明它显然没有这样做它应该是什么。
好的文档规则如下。它们都基于一个简单的想法：文档应该维护，维护不是免费的，而且文档很难甚至不可能测试，所以它们中的任何错误往往会在人们意识到错误之前徘徊很长时间。就像在编写代码时一样，如果您不必要地花费 10 行来编写本可以在 2 中同样有效地完成的代码，那么您就搞砸了。这同样适用于文档。不要重复自己，不要提供无意义或多余的信息。说清楚，说简洁。
如果因为方法名称准确地描述了方法的全部性质而没有什么要补充的，那么不要记录它。方法名是文档。让它自立。
如果您确实有要添加的内容，但描述的内容 returns 完全涵盖了它，那么 只需 写下
@return标签.这很好：
/**
* @return amount of drinks in the fridge.
*/
public int countDrinks() { ... ... }
你在这里有 javadoc 的唯一原因是因为有人认为提及 'in the fridge' 是值得的。当然，这仍然是糟糕的代码风格：
class Fridge {
/**
* @return The amount of drinks in the fridge.
*/
public int countDrinks() { ...... }
}
这很糟糕，因为 'in the fridge' 在这里不是有用的信息。呃，当然在冰箱里。它位于名为 Fridge 的 class 中。想一想：程序员可能对 Fridge 的 countDrinks 方法的作用感到困惑，但 javadoc @return The amount of drinks in the fridge. 为他们澄清了一切。当然，这些几率是 0%，而且还没有四舍五入。
教训是：防止不良代码风格、难以维护代码和其他类似风格指南的流程是您无法仅用软件和规则包解决的问题。这是人类的事：你致力于团队内培训、招聘实践、代码审查流程，以及一种普遍的文化，人们应该关心代码的 objective 质量，而不是挂在过度强制的测量上，例如 'does the codebase pass some style-checker ruleset?'，只有当你所有这些都建立起来之后，你才能考虑得到一些软件来轻松地帮助你完成团队的需求。
我意识到这是因为 Eclipse 会在您按回车键时自动在星号后插入一个 space（如果您要在线上写东西，这是有意义的）但不会在您按下时删除它再次按回车。所以 Javadoc 标记之前的行实际上是：<leading indentation>*<space>。删除此 space 会为我手动删除 Checkstyle 警告。
也许其他人知道如何配置 Eclipse 以自动删除此 space。就个人而言，我坚持使用 Google's XML formatter profile because their google-java-format Eclipse plugin 不起作用（未处理的异常）。也许 google-java-format 会解决这个问题。
我的解决方案是
使用正则表达式搜索 \* $，然后将所有内容替换为 *.