自我记录代码与Javadocs？

最近，我一直在努力重构当前正在处理的部分代码库-不仅可以自己更好地理解它，而且还可以使其他从事代码工作的人更容易理解。

我倾向于认为自记录代码很好。我只是认为它更干净，并且如果代码能说明一切，那 ... 很好。

另一方面，我们有诸如javadocs之类的文档。我也喜欢这个，但是这里的评论（当然还有一般的评论）也有过时的风险。但是，如果它们是最新的，那么理解复杂的算法就非常有用。

最佳做法是什么？您如何在自我说明代码和javadocs之间划清界限？

自我记录代码（和代码内注释）和Javadoc注释具有两个非常不同的目标受众。

保留在代码文件中的代码和注释供开发人员使用。您想在这里解决他们的疑虑-轻松了解代码的作用以及代码的工作方式。通过使用适当的变量名称，方法，类等（自文档代码）以及注释，可以实现此目的。

Javadoc注释通常是针对API用户的。他们也是开发人员，但他们并不关心系统的内部结构，而只关心系统的类，方法，输入和输出。该代码包含在一个黑框中。这些注释应用于解释如何执行某些任务，预期的操作结果，何时引发异常以及输入值的含义。给定一个Javadoc生成的文档集，我应该能够完全了解如何使用您的界面，而无需查看任何代码。

代码说明了如何。评论说了为什么，甚至为什么没有。

为您的代码的未来读者和维护者提供您的工作是您的工作。将所有您可以的放入代码中，其余的放入注释中。

请注意，最难捕捉的是设计决策-也要记住这些决策。

使用Javadocs并没有真正的区别-由于生成的文档包含函数名称以及注释中的文本，因此绝对没有理由要在注释中重复任何从函数名称本身显而易见的内容。

另一方面，如果您具有一个必须首先查看实现以了解其优点的功能（因此该信息无法提供给Javadocs），那么该代码是恕我直言，无论如何实现的清晰程度。

我认为使用javadocs时，一切都与使用任何文档相同-主要规则是：

跟随观众

有很多人读过您的javadocs吗？如果是的话，那么为使它正确而付出努力是很有意义的。

您的读者是否倾向于跳过阅读代码以学习Javadocs？如果是的话，那么花很多精力在编写上就有意义了。

• JDK文档就是这种情况。Guess Sun / Oracle在这些方面花费了很多精力，并且在社区中大量使用的API文档中，他们似乎获得了可观的回报。

现在，这是您的情况吗？如果没有，请三思而后行，投入到javadocs上的努力是否合理。

正如上面已经指出的那样，听取观众的意见以找出方法。

• 如果您听到有关文件不足的积极抱怨，请考虑投资进行改进。
   
  另一方面，如果您所听到的只是开发人员对脑残规则的抱怨，迫使他们浪费时间在无用的类型上，那么您的javadocs努力就很可能像投资次贷。而是考虑更好的投资。

我只想评论Javadoc注释可能过时的问题。@JonathanMerlet正确地表示Javadoc应该是稳定的，但是您也可以在同行评审期间通过复审Javadoc和注释以及代码来提供帮助。注释与代码的功能匹配吗？如果不是，那是不正确的，并坚持要求开发人员对其进行修复。尝试鼓励其他开发人员也这样做。这不仅有助于使外部文档（Javadoc注释）保持最新，而且还可以使所有常规代码注释保持最新。这有助于在重构之后出现的开发人员更快，更轻松地理解代码，并使将来的维护变得更加简单。

我认为javadocs适用于应该保持稳定（API）的部分，以使注释过期的风险降到最低，而自我记录代码对于频繁更改（实现）的东西非常有用。当然，API可能会在项目进行过程中发生变化，但是在声明之前放置标头，使两者保持同步并不难（与解释多行代码的多行注释相比）