java - 我应该记录不言自明的私有方法吗？（爪哇）

Question

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

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

• 遵守所有手续，如参数、返回值和异常的描述
• 如果我应该记录不言自明的私有方法，例如fireSomeEvent哪里是显而易见的，因为这只会使代码混乱

对此的标准方法是什么？

Answer 1

是的。

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

即使是使用代码的人也会查看代码的源代码，即使它已记录在案。这有助于客户更好地了解图书馆。通过添加文档，您也可以让客户更容易理解您的代码。

Answer 2

我个人记录了以后可能导致歧义的任何内容。我不会记录

def next = counter.incrementAndGet()

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

此外，在私有方法中，我个人不会担心遵守 Javadoc 标准。只要写一些评论，你就在我的好书中。我不需要@param 或@return。这些是针对公共 API 的。