方法/类评论是否应始终如一地应用或仅在需要的基础上？

Question

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

那么描述方法或类的注释是否应该以一致的方式应用，或者只有在定义中的含义不完全清楚时才会写出这样的注释？

Answer 1

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

所以最好编写自解释代码。此外，没有必要为像setter和getters这样显而易见的事情写评论。

所以我会选择这样的评论只有在定义中的含义不完全明确时才会写出来。

Answer 2

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

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