Class 方法/类别评论是否应持续应用，还是仅在需要的基础上应用？

为了保持一致性，我总是将注释（以JavaDoc的形式）应用于所有方法和类，即使它们是简单的getter和setter方法或非常小的包装类。但我也在努力编写自我记录的代码，这常常会使注释变得多余；i、 e.只在需要的地方写注释（在写之前，试着重写代码，这样你就根本不需要注释）。因此，这两种方法似乎相互矛盾

---

那么，描述一个方法或类的注释应该以一致的方式应用，还是应该仅在定义的含义不完全清楚时才编写此类注释？

一个简单的试金石测试是检查类的注释是否多于代码。如果是的话，那就意味着你的代码太复杂，很难为任何人使用

因此，最好编写自解释代码。此外，对于像setter和getter这样显而易见的东西，也不需要写注释

---

因此，我会选择只有在定义中含义不完全清楚时才编写此类注释。

我以前为每个方法创建代码，但现在我只在注释添加了比代码本身更多的信息时才创建文档

下面是一篇关于类似主题的文章，有很多答案。

---

随着代码的发展，文档的更新有可能被“遗忘”。参考链接中的问题，糟糕的文档比没有文档更糟糕。

我同意糟糕的文档比没有文档更糟糕，但是如果文档是好的，但是多余的呢。如果没有任何文档，它还会更好吗？我想这要视情况而定。如果它真的是多余的，那么它就不需要了，因为它浪费了开发人员的精力。否则，如果代码是作为API的一部分编写的（这意味着许多API用户将阅读文档），则建议为类的每个方法编写一致的文档，换句话说，即使是完美无瑕的文档，也有助于识别某些代码可能需要做哪些更改，将增加实际进行此类更改所需的工作，因为必须更新文档以匹配代码。如果确定修复内容所节省的时间超过了维护文档的额外成本，那么文档就是一种帮助。如果没有，这可能是一个障碍。虽然我还没有正式阅读过它，但我认为应该区分为满足特殊需要而存在的数据类型和方法，这样人们就不应该真正尝试在使用它的上下文之外去理解它，而不是那些设计为更普遍有用的数据类型和方法。这种区别可能跨越私有/公共边界，尤其是应用于数据类型时。如果一个可以跨线程调用的公共方法需要向调用者返回三个值，我建议最好为此定义一个最小的结构，除了“三个字段，名称/类型（无论什么），包含调用者放在那里的任何内容”之外，没有真正的规范，然后让返回结构的方法描述它放在那里的内容。如果代码不是API，我接受这一回答。如果是，那么我很可能会采用一致性方法。