Checkstyle警告即使有一行,也应以空行开头

6vl6ewon  于 2022-09-21  发布在  Eclipse
关注(0)|答案(5)|浏览(258)

我在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)上,也不需要使用超文本标记语言。

谢谢你的帮助!

kx1ctssn

kx1ctssn1#

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

也许其他人知道如何将Eclipse配置为自动删除此空间。就我个人而言,我坚持使用Google's XML formatter profile,因为他们的Google-Java格式的Eclipse插件不能工作(未处理的异常)。也许谷歌的Java格式可以解决这个问题。

iqih9akk

iqih9akk2#

我的解决办法是
使用正则表达式搜索\* $,并仅用*替换所有。

u3r8eeie

u3r8eeie3#

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

eqoofvh9

eqoofvh94#

这在NetBeans(12.6)中也会发生。似乎很常见。我发现,如果您删除在行前面加上*的选项,问题就会消失。例如,如下所示:

/**
 JavaDoc Summary.

 @since 1.0.0
 @author javafueled
 */

我一般不喜欢这种格式,所以我得记得把台词改好。@since;)NetBeans不提供自动更正该错误的方法。

62o28rlo

62o28rlo5#

检查该位置的确切字节数。上面可能有一个实际的字符,比如一个不间断的空格;文字处理程序通常会把你的输入“花哨”起来,然后把它们变成奇怪的字符。例如,如果你把“Hello”粘贴到Word中,然后再粘贴回Java中,它不再是一个字符串常量,因为Word决定把它们变成 curl 引号:“Hello”,这不是Java。同样的策略也可以用来偷偷地进入不间断的空间等。绝大多数空白Unicode字符都被视为空格,但在这方面,检查样式插件可能会被破坏(它只会认为空格和制表符无关紧要)。或者,CheckStyle可以是“需要”在空行上的*之后加一个空格,这样该行上的完整字符集就是\t *(制表符、空格、星号、空格)。

但最重要的是...

你的流程被打破了。你有一个样式检查器,你现在关注的是一些完全不相关的东西,但你的javadoc很可怕

您大概有一个名为countDrinksInFridge()的方法,并且您用javadoc“记录”了这个方法,它为您提供了完全无用的非信息,并且执行了两次,以引导!DRY在编程中几乎被公认为一个奇妙的原则,这是有原因的,而您刚刚违反了它。两次,不少于两次。

样式检查器抱怨您使用了哪种类型的空格字符,但却认为编写愚蠢的javadoc非常棒,这一事实应该足以证明它显然没有做它应该做的事情。

好的文档规则如下所示。它们都基于一个简单的理念:应该维护文档,维护不是免费的,文档很难测试,所以它们中的任何错误往往会持续很长一段时间,然后才会有人意识到它是错误的。就像在编写代码时一样,如果您不必要地用10行代码来编写本可以在2行中同样高效地完成的事情,那么您就搞砸了。这同样适用于文档。不要重复自己,不要提供无意义或多余的信息。说得清楚,说得简明扼要。

  • 如果因为方法名称准确地描述了方法的整个性质,所以您没有更多要添加的内容,那么不要记录它。方法名称Documentation。让它自己站起来吧。
  • 如果您确实有要添加的东西,但描述它返回的内容完全涵盖了它,那么只需编写@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的类中。想想看:程序员可能会对FridgecountDrinks方法的作用感到困惑,但javadoc @return The amount of drinks in the fridge.为他们澄清了这一点。当然,这些几率是0%,这甚至没有四舍五入。

教训是:防止糟糕的代码风格、难以维护的代码和其他类似风格指南的想法的流程是您不能仅使用软件和规则包来修复的。这是人类的事情:你从事团队内的培训,你的招聘实践,代码审查过程,一种普遍的文化,人们应该关心代码的客观质量,而不是过于强制的衡量标准,比如,代码库是否通过了一些样式检查器规则集?只有在所有这些都建立之后,你才可以考虑让一些软件来轻微地帮助你完成团队的需求。

相关问题