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

【问题标题】：Should method/class comments be consistently applied or on a need basis only?方法/类注释应该一致地应用还是仅在需要的基础上应用？
【发布时间】：2010-09-18 08:40:08
【问题描述】：

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

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

【问题讨论】：

标签： class methods comments consistency self-documenting-code

【解决方案1】：

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

所以最好编写自我解释的代码。此外，对于像 setter 和 getter 这样显而易见的东西，也无需编写 cmets。

所以我会选择只有在定义中含义不完全清楚时才编写此类 cmets。

【讨论】：

如果代码不是 API，我接受此作为答案。如果是，那么我很可能会改用一致的方法。

【解决方案2】：

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

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

【讨论】：

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