class - 方法/类注释应该一致地应用还是仅在需要的基础上应用？

Question

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

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

Answer 1

一个简单的试金石是检查该类是否有比代码更多的注释。如果是，则意味着您的代码太复杂并且难以为任何人使用。

所以最好写自我解释的代码。此外，对于像 setter 和 getter 这样明显的东西也不需要写注释。

因此，只有当定义中的含义不完全清楚时，我才会写这样的评论。

Answer 2

我曾经为每种方法创建代码，但现在我只在备注添加的信息比代码本身更多时创建文档。

这是一个关于类似主题的问题，有很多答案。随着代码的发展，文档的更新有可能被“遗忘”。参考链接坏文档中的问题比根本没有文档更糟糕。