java - 如何在 Java 代码中执行文档？

Question

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

查看了 FindBugs、PMD 和 CheckStyle，但它们似乎不提供此功能。

Answer 1

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

Checkstyle可以查if Javadoc is present ，但它无法检查 Javadoc 是否包含 @param pMyParam myParam 和其他无意义的垃圾。即使你让一些工具检查文档的内容，这也会产生大量的误报，并导致简单但有用的评论被夸大，只是为了取悦检查工具。一段时间后，开发人员将学会在阅读代码时过滤掉 Javadoc，就像我们在阅读网页时过滤掉广告一样。因此，如果开发人员不想编写优秀且有用的文档，那么所有工具都将一事无成。

用 Antoine de Saint-Exupéry 的话来说:如果你想造一艘船，不要召集人们去收集木材，也不要给他们分配任务和工作，而是教他们他们渴望大海的无尽浩瀚。

我的建议是:使用 checkstyle 来检查最基本的东西，例如每个类至少有一个类型注释，以及接口(interface)也记录它们的方法。然后，在必要时教育开发人员什么是有意义和有用的文档，并明确表示在开发主管的眼中，高质量的代码有高质量的文档。即使根本没有记录某些方法，Javadocs 也可能非常好。然后只能通过人工检查来进行检查，例如通过同行评审或质量控制过程中的某种形式化步骤。

只是我的两分钱。