我应该记录不言自明的私人方法吗？ （JAVA）

Question

我喜欢正确记录的代码，对于我来说，使用正确记录的描述合同的公共方法是明智的，同样适用于私有或包内部方法来解释代码内部/实现。

但是我不确定我是否应该使用非公开和不受保护的方法：

• 遵守所有手续，如参数说明，退货值和例外
• 如果我应该记录像fireSomeEvent这样的不言自明的私有方法，那么乍一看它的作用是显而易见的，因为这只会使代码混乱

这是什么标准方法？

Answer 1

是

如果有人要查看您的代码，请记录。它值得额外的一两行。您的代码将显得更加一致和清晰。如果其他任何人都会查看您的代码，您应该明确地发表评论。

即使是使用代码的人也会查看代码的源代码，即使它已被记录。这有助于客户更好地理解库。通过添加文档，您可以更轻松地为客户理解代码。

Answer 2

我个人记录了以后可能引起歧义的任何事情。我不会记录

def next = counter.incrementAndGet()

作为其自我解释。任何认为你应该记录这样的方法的人手上都有太多的时间。

另外，在私人方法中，我个人不担心遵守Javadoc标准。只需在我的好书中写下一些评论即可。我不需要@param或@return。这些是公共API。