如何在 Java 代码中强制执行文档?

问题描述 投票:0回答:5

有哪些选项可以强制记录代码?我想要一些将作为构建过程的一部分运行的东西,例如一个 Maven 目标,它将检查代码是否已记录(类级别和方法级别)并报告是否有任何代码缺少文档。

看过 FindBugs、PMD 和 CheckStyle,但它们似乎没有提供此功能。

java findbugs checkstyle pmd
5个回答
3
投票

好吧,我不想告诉你这一点,但有用的文档不能使用工具来强制执行。

Checkstyle 可以检查 Javadoc 是否存在 ,但它无法检查 Javadoc 是否包含

@param pMyParam the myParam
以外的任何内容以及其他无意义的垃圾。即使您让某些工具检查文档的内容,这也会产生大量误报,并导致简单但有用的注释被夸大,只是为了取悦检查工具。一段时间后,开发人员将学会在阅读代码时过滤掉 Javadoc,就像我们在阅读网页时过滤掉广告一样。因此,如果开发人员不想要编写良好且有用的文档,那么所有工具都不会为您带来任何好处。

用安东尼·德·圣埃克苏佩里(Antoine de Saint-Exupéry)的话来说:如果你想建造一艘船,不要召集人们一起去收集木材,不要给他们分配任务和工作,而是教会他们渴望一望无际的大海。

我的建议是:使用 checkstyle 检查最基本的知识,例如每个类至少有一个类型注释,并且接口也记录了它们的方法。然后,在必要时对开发人员进行教育,让他们了解什么是有意义且有用的文档,并明确表示在开发主管眼中,高质量的代码具有高质量的文档。即使某些方法根本没有文档记录,Javadoc 也可能非常好。然后只能通过手动检查来完成检查,例如通过同行评审或质量控制过程中的某种正式步骤。

只是我的两分钱。


1
投票

也许这并不完全是您正在寻找的,但您可以使用 Sonar 并在编译代码时调用它。 Sonar 将提供大量信息,包括 checkstyle

Sonar 非常易于使用并与 Maven 项目集成。

文档:http://docs.sonarqube.org/display/SONAR/Installing+and+Configuring+Maven


1
投票

Teamscale可以检查评论是否缺失。它还可以评估评论的质量并揭示琐碎和不相关的评论。

免责声明:我是 Teamscale 开发人员。


0
投票

不久前,Sun 有一个名为 DocCheck 的 doclet。从 javadoc 创建报告。不知道现在还有没有..

进行谷歌搜索。

好的,谷歌搜索...适用于 1.2、1.3 和 1.4 版本。它是实验性的并且似乎不活跃。现在值得用吗?我不知道。这是由你决定的事情。

javadoc 文档检查下载

http://192.9.162.55/j2se/javadoc/doccheck/index.html


0
投票

如果使用 Maven Javadoc 插件,您可以使用

failOnWarnings
参数强制执行任何 Javadoc 警告(针对几乎所有缺失的 Javadoc 发出的警告)将使您的构建失败,例如

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <configuration>
    <failOnWarnings>true</failOnWarnings>
  </configuration>
</plugin>

请注意,其他答案仍然适用,并非所有 Javadoc 都一定有用。

另一个问题是,如果您使用 Lombok 或类似的自动生成代码的工具,但不会自动生成关联的 Javadoc,那么这将使您的构建失败(NB Lombok 可以将 Javadoc 添加到某些,但不是全部) ,生成的代码)。因此,如果您想使用这些类型的工具,您必须选择执行 Javadoc 注释的严格程度。

© www.soinside.com 2019 - 2024. All rights reserved.