是否需要在方法签名中为每个参数编写一个Javadoc注释？

我们团队中的一位开发人员认为，有必要为方法签名中的每个参数编写一个Javadoc注释。我认为这不是必要的，实际上我认为这甚至是有害的。

首先，我认为参数名称应具有描述性和自我记录性。如果您的参数的用途不是很明显，那么您可能做错了。但是，我确实知道，有时不清楚参数的用途，因此在这种情况下，应该编写一个Javadoc注释来解释该参数。

但是我认为没有必要对每个参数执行此操作。如果该参数的作用已经很明显，则javadoc注释是多余的；您只是为自己创造了额外的工作。此外，您还为需要维护代码的任何人创建了额外的工作。方法会随着时间而变化，维护注释几乎与维护代码一样重要。您有多少次看到“ X是Y导致Z原因”这样的注释，只是看到该注释已过时，实际上该方法甚至不再使用X参数？它总是发生，因为人们忘记了更新评论。我认为，误导性评论比根本没有评论更具危害性。因此存在过度注释的危险：通过创建不必要的文档，您可以

但是，我尊重团队中的另一个开发人员，并接受他也许是对的，但我错了。这就是为什么我会向其他开发人员提出您的问题：确实有必要为每个参数编写一个Javadoc注释吗？在此假设该代码是我公司内部的代码，任何外部方都不会使用。

Javadoc（以及Microsoft Word中的XMLDoc）注释不是注释，而是文档。

注释可以像您希望的那样稀疏。假设您的代码具有一半可读性，那么普通注释仅是路标，以帮助将来的开发人员理解/维护已经盯着他们看了两个小时的代码。

该文档表示代码单元与其调用者之间的合同。它是公共API的一部分。总是假设的Javadoc / xmlDoc中，将在帮助文件中或在自动完成/智能感知/代码完成弹出要么结束了，谁是人可以观察到不检查你的代码的内部，而只是想使用它的一些目的他们自己的。

参数/参数名称永远不言自明。您总是以为他们是在过去的一天中编写代码的时候，但是尝试在两周的假期后再去学习它，您会发现它们实际上是多么无助。

不要误会我-为变量和参数选择有意义的名称很重要。但这是代码问题，而不是文档问题。不要从字面上太理解“自我记录”一词；这是在内部文档（注释）的上下文中，而不是在外部文档（合同）的上下文中。

要么评论所有内容，要么什么都不评论（显然，评论所有内容是更好的选择）。考虑有人使用您的代码，直接在您的源文件或生成的doc文件（即doxygen输出）中查看您的API。通常不一致导致混乱，从而导致花费的时间，通过源挖掘弄清楚为什么事情没有评论，这导致浪费的时间本来是可以避免的是刚刚在第一时间被评价参数。

切记：不管您认为多么平凡，其他人对您有意义的事情可能会有完全不同的解释（想想一个不太懂英语并试图理解您的代码的人）。

话虽如此，如果其他开发人员强调记录所有内容的重要性，那么就需要尽可能多地强调（如果不是更多的话）使文档保持最新。如您所述，没有什么比过时的评论更糟了（如果不如被遗漏的文档还差的话，同样糟糕）。

让我们从一个假设开始，即开发人员周期是我们试图保留的资源。

因此，这意味着开发人员不应浪费时间记录不明参数和返回值，对吗？

好吧，让我们分解一下。

如果我们记录所有内容，假设边际评论确实微不足道并且不需要思考或研究，那么成本就是实际键入评论和修正错字的额外时间。

如果我们选择，那么成本为：

• 与您团队中其他认为应该记录所有内容的开发人员一起赢得争论。
• 对于每个参数，确定是否应该对此进行记录。
• 当有人对是否应该记录参数有不同意见时，与您的团队进行更多讨论。
• 花费时间寻找代码并研究被认为是不言自明的参数时，事实并非如此。

因此，我倾向于只记录所有内容。缺点是肯定的，但可以控制。

如果您仍在编写Javadoc，则最好完全编写它，甚至包括“显而易见的”参数。对于您或其他开发人员来说，它们可能是显而易见的，但是任何正在研究它的人都将从知道每个参数的意图中受益。

为了正确地维护Javadoc，您需要使用一些开发工具来帮助您实现这一目标。想到了Eclipse。当然，如果这很重要，则必须确保团队中的每个人都在维护代码，包括评论在内。

不要忘记在与代码分开时可以使javadoc可见，最主要的例子就是Java API本身。如果不为方法中的每个参数都包含javadoc，则会误解该方法及其用法。

“必要”是完全主观的。我认为您要问的是，“根据您的情况，应该添加javadoc注释”。不知道您的应用程序的范围或上下文，我们如何知道什么适合您？

如果此公开代码（例如，供其他人访问的代码，例如api），则记录每个参数。不要假定读者像您一样了解项目。但是，否则，由您和您的团队自行决定。