Java 文档中的私有成员变量
为什么 getter/setter 使用的私有成员变量应该在描述相应 getter 和 setter 的 javadoc 中指定其描述。
Why should private member variable used by getters/setters have their description specified in the javadocs describing the corresponding getters and setters.
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（2）
私有变量的描述，如下所示：
... 不应包含其 getter 和 setter 的描述。它应该包含该变量的属性、不变量（例如 永远不应该为 null）以及类似的内容。
编辑：
啊，我误读了你的问题。您问为什么 getter/setter 的描述应该包含变量的描述，而不是相反。
他们不应该——甚至不必存在这样的变量。 getter 和 setter 应该描述它们所具有的效果，其中可能包括对该对象的某些抽象属性的修改（或检索）。该属性由私有变量实现是不相关的。
The description of the private variable, like here:
... should not contain descriptions of its getters and setters. It should contain properties of this variable, invariants (like should never be null), and similar.
Edit:
Ah, I misread your question. You asked why the description of the getters/setters should contain a description of the variable, not the other way around.
They should not - there even does not have to exist such a variable. The getters and setters should describe the effect they are having, which may include the modification (or retrieval) of some abstract property of this object. That this property is implemented by a private variable is not relevant.
JavaDocs 的目的是记录代码的公共 API，以便开发人员可以了解如何使用您的类。其目的不是公开代码的内部工作原理。记录私有成员只会让 API 文档更难阅读。
私有成员的含义仅对那些阅读/维护您的代码的人感兴趣。它们的目的应该通过清晰、明确的命名和代码的整体优雅来传达。理想情况下，您甚至不需要评论。
The purpose of JavaDocs is to document the public API of your code so that developers can understand how to use your classes. It's purpose is not to expose the internal workings of your code. Documenting private members will just make you API documentation harder to read.
The meaning of private members is only of interest to those who read/maintain your code. Their purpose should be conveyed through clear, unambiguous naming and the general elegance of your code. Ideally you shouldn't even need comments.