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

Question

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

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

Answer 1

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

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

@param pMyParam the myParam

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

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

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

只是我的两分钱。

Answer 2

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

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

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

Answer 3

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

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

Answer 4

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

进行谷歌搜索。

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

javadoc 文档检查下载

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

Answer 5

如果使用 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 注释的严格程度。