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

【问题标题】：How can I enforce documentation in Java code?如何在 Java 代码中强制执行文档？
【发布时间】：2013-03-25 10:09:03
【问题描述】：

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

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

【问题讨论】：

标签： java findbugs checkstyle pmd

【解决方案1】：

Teamscale 可以检查 cmets 是否丢失。它还可以评估 cmets 的质量并揭示琐碎和无关的 cmets。

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

【讨论】：

【解决方案2】：

也许它不是您正在寻找的，但您可以使用Sonar 并在编译代码时调用它。 Sonar 会提供很多信息，包括 checkstyle

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

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

【讨论】：

Sonar 为此使用了 Checkstyle。不过，这是一个很棒的工具！但比单独的 Checkstyle 更重量级和更强大。

【解决方案3】：

不久前有一个来自 Sun 的名为 DocCheck 的 doclet。从 javadoc 创建报告。不知道还有没有。。

进行谷歌搜索。

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

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

【讨论】：

如果您要回答一个问题，为什么在回答之前不进行谷歌搜索？如果该工具不再存在，为什么还要提及它。
这是 2006 年的 DocCheck Maven plugin，尽管它链接到一个损坏的页面以下载 doclet。换句话说，它似乎完全没用。

【解决方案4】：

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

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

用安托万·德·圣埃克苏佩里的话来说：如果你想造一艘船，不要召集人们一起收集木材，不要给他们分配任务和工作，而要教导他们渴望无边无际的大海。

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

只要我的两分钱。

【讨论】：

JAutodoc 可以自动生成 Javadoc cmets。以防万一。
是的，如果文档不是由真正希望读者理解的人编写的，那么文档可能毫无用处。用工具强制执行是没有意义的。工具对于获取覆盖率和查找未记录的代码很有用，但对质量没有帮助。