方法/类注释应该一致应用还是仅根据需要应用？
为了保持一致性，我总是对所有方法和类应用注释（以 JavaDoc 的形式），即使它们是简单的 getter 和 setter 方法或非常小的包装类。但我也在努力编写自记录代码，这通常使注释变得多余；即只在需要的地方写注释（在这样做之前，尝试重写代码，这样你就根本不需要注释）。因此，这两种方法似乎是相互矛盾的。
那么，描述方法或类的注释应该以一致的方式应用，还是应该仅在定义中含义不完全清楚时才编写此类注释？
For consistency, I've always applied comments (in the form of a JavaDoc) to all methods and classes, even if they are simple getters and setters methods or very small wrapper classes. But I'm also striving to write self-documenting code which often makes comments superfluous; i.e. write comments only where needed (and before doing that, try to rewrite the code so you don't need the comment at all). Hence, these two approaches appear to be contradictory to each other.
So should comments which describe a method or class be applied in a consistent manner, or should such comments be written only when meaning is not completely clear from the definition?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（2）
一个简单的试金石是检查类的注释是否多于代码。如果是，则意味着您的代码太复杂并且难以供任何人使用。
所以最好编写不言自明的代码。此外，也不需要为 setter 和 getter 等显而易见的东西编写注释。
所以我会同意只有当定义中含义不完全清楚时才写这样的注释。
A simple litmus test would be to check if the class has more comments than the code. If yest then it means that your code is too complex and is hard to use for anyone.
So it is best to write self explanatory code. Also there is no need to write comments for things that are obvious like setters and getters.
So I would go with such comments be written only when meaning is not completely clear from the definition.
我曾经为每个方法创建代码，但现在我只在注释添加比代码本身更多的信息时创建文档。
这是一个问题关于类似的主题有很多答案。
随着代码的发展，文档的更新有可能被“遗忘”。参考链接中的问题，错误的文档比根本没有文档更糟糕。
I used to create code for every method but now I only create documentation when the remarks add some more information than the code itself.
Here is a question on a similar topic with lots of answers.
As the code evolves there is a chance that the update of the documentation is "forgotten". Referring to the question in the link bad documentation is worse than no documentation at all.