我应该记录不言自明的私有方法吗？（Java）[关闭]答案

【问题标题】：Should I document the self-explanatory private methods? (Java) [closed]我应该记录不言自明的私有方法吗？（Java）[关闭]
【发布时间】：2014-04-17 23:35:10
【问题描述】：

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

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

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

对此的标准方法是什么？

【问题讨论】：

我会说这样做，cmets 可以稍后删除（并通过源代码管理恢复），但以后实现会比较棘手，即使方法非常明显。
“不言自明”是一个危险的词；对你来说显而易见的事情可能对其他人来说并不明显。也就是说，如果您有一个具有好名称的单行方法（即名称反映了该方法的目的，而不仅仅是它发生的事情），您可能会争辩说文档没有添加任何内容。另一方面，一致的文档风格有助于程序在视觉上保持一致，并使读者更容易找到东西；另外，这意味着javadoc可以使用您的方法。
“文档”和“评论”是有区别的。大概不需要正式的文档，但是代码应该还是有合适的 cmets。
@BheshGurung 当他们看不到它时，他们就看不到它。这些 cmets 适用于从事此类工作的其他开发人员。更重要的是：对于首先实施它的人。没有什么比（用文字）解释它的作用更能迫使你质疑自己的代码了。
就个人而言，如果您编写巫术代码，例如长 if 语句、十六进制数学、二进制算术、密码学等，请让 cmets 了解您的代码所做的什么。如果该行简单明了，没有花哨或复杂的内容，则不需要注释。

标签： java code-structure

【解决方案1】：

是的。

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

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

【讨论】：

【解决方案2】：

我个人会记录以后可能会引起歧义的任何内容。我不会记录

def next = counter.incrementAndGet()

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

另外，在私有方法中，我个人不会担心遵守 Javadoc 标准。只需编写一些 cmets，您就可以在我的好书中。我不需要@param 或@return。这些用于公共 API。

【讨论】：

完全正确。我个人不会写一个不是自我记录的私有方法。私有方法的全部意义在于隐藏公共 api 下的复杂性。因此方法 public Account getAccountIfGrantedAccess() 调用方法 checkPermissionsOfHttpRequestUser() getAccountFromDatabase() 我认为没有理由记录除公共方法必须提供给调用者之外的任何内容。