javadoc - Java 文档中的私有成员变量

Question

为什么 getter/setter 使用的私有成员变量应该在描述相应 getter 和 setter 的 javadocs 中指定它们的描述。

Answer 1

私有变量的描述，像这里：

/**
 * the name of this object.
 */
private String name;

... 不应包含对其 getter 和 setter 的描述。它应该包含这个变量的属性、不变量（永远不应该是 null）和类似的。

---

编辑：啊，我误读了你的问题。您问为什么 getter/setter 的描述应该包含变量的描述，而不是相反。

他们不应该 - 甚至不必存在这样的变量。getter 和 setter 应该描述它们所具有的效果，其中可能包括对该对象的某些抽象属性的修改（或检索）。该属性由私有变量实现是不相关的。

Answer 2

JavaDocs 的目的是记录您的代码的公共 API，以便开发人员可以了解如何使用您的类。它的目的不是暴露代码的内部工作原理。记录私有成员只会让你的 API 文档更难阅读。

私有成员的含义仅对阅读/维护您的代码的人感兴趣。它们的目的应该通过清晰、明确的命名和代码的总体优雅来传达。理想情况下，您甚至不需要评论。