私有和受保护的变量，方法和类是否应该被注释？

Question

创建私有或受保护的变量，方法，类等时，是否应该使用文档注释进行评论？

Answer 1

是的！这些评论旨在帮助任何开发人员 - 包括您自己 - 在审查，维护或扩展代码时。无论是公共/私人都不应该是一个影响因素，如果你认为某些内容在没有评论的情况下不够明确，那就把它放进去吧。

（当然，最好的文档首先是清晰的自我记录代码）

Answer 2

有些人无疑会告诉你没有任何需要进行评论（从技术上讲，他们是正确的，因为评论对输出没有影响）。但是，这就像你将它标记为“编码风格”一样。除了给它们一个描述性名称外，我个人总是评论所有变量。请记住，其他人可能希望使用您的来源，或者您可能希望在几年内使用，在这种情况下，在您仍然知道它的作用的情况下记录它是值得的几秒钟。

Answer 3

肯定是的。例如，当您在三个月后发现代码中的错误时，通过评论可以更容易地回想起此代码应该执行的操作。

Answer 4

评论单个变量偶尔会有所帮助，但通常情况下，变量将具有可以支持某些不变量的逻辑分组。描述整个群体应该如何表现的评论通常比描述个体变量的评论更有用。

例如，如果Java中的EditablePolygon类可能包含四个基本字段：

int[] xCoords;
int[] yCoords;
int numCoords;
int sharedPortion;

并且期望保持不变量，两个数组将始终具有相同的长度，并且该长度将是＆gt; = numCoords，并且所有感兴趣的坐标将位于numCoords以下的数组槽中。它可以进一步指定可能存在共享相同数组的多个EditablePolygon对象，前提是除了一个这样的对象之外的所有对象都具有大于sharedPortion或等于数组长度的numCoords，并且一个对象的sharePortion不小于任何其他对象的numCoords值[制作形状的克隆需要防御性副本，除非要求对与克隆共享的原始部分进行更改，或克隆的任何部分[与原文完全共享]。

请注意，文档注释最重要的事情是（1）数组长度可能超过点数，（2）数组的某些部分可能是共享的。第一个可能在代码中有些明显，但第二个可能远不那么明显。字段sharedPortion确实具有某种意义，但其含义和目的实际上只能与其他变量相关联。

Answer 5

记录方法和类是一种很好的做法。此外，公共方法的javadoc应该更加强调，因为它们作为外部对象的参考手册。类似地，Javadoc可能对公共变量有益，但我个人并不赞成对变量进行评论。