什么时候评论“太多”，何时他们还不够？

Question

正在进行一场小型辩论，我会在代码中研究评论的功效。其中一位负责人指示他的开发人员不要使用评论，因为他们过于“老式”，而其他几位开发人员表示他们从不使用评论，因为他们觉得他们所做的一切都使代码混乱。

我一直非常坚持使用基本注释块对每个文件的顶部进行注释，对每个方法/类/ etc定义进行注释，然后我在代码中的任何地方进行注释，我认为我可能会来在6个月后回想起“WTF”。

显然这是主观的，但我很想知道是否有人对这种或那种方式有任何非常好的论据或经验。

Answer 1

这已被讨论过死亡。

我只会指出你Jeff Atwood's wonderful post on the subject，它会钉在头上。

Answer 2

在我的整个职业生涯中，我从未遇到过那种美妙的野兽“自我记录的代码”。也许我只是不走运，但我开始怀疑它实际上并不存在。

Answer 3

每隔一段时间我就会遇到如此优雅的分区代码，有一个非常明显的方法，字段和变量名称，我需要知道的一切都是从代码中可以看出的。

在一般情况下，只有非常棒的代码专家才会编写这样的代码。我们其余的人凑齐了一些有效的东西。

• 如果你是一个非常棒的代码大师，不要用多余的评论来玷污你的神圣代码。
• 如果你几乎不知道自己在做什么，请小心记录你的浮躁尝试，以便其他人可以试图挽救这些混乱。
• 如果你是平均水平（我们大多数人都是，按照定义），那么在自己和他人的评论中留一些提示，以便在维护时更轻松，但不要通过记录来侮辱任何人的智慧和浪费空间真的很明显。理想情况下，您的评论应该在元级别描述您的代码，而不是表明您正在做什么，而是为什么。另外，如果你做了一些不寻常或棘手的事情。

Answer 4

“其中一位负责人指示他的开发人员不要使用评论，因为他们过于”过时“，而其他几位开发人员表示他们从不使用评论，因为他们觉得他们所做的一切都使代码混乱。” / p>

如果我听过一位开发人员，我正在处理这样的谈话，我会纠正他们。如果我没有必要的等级来纠正它们，我会离开这份工作。

非常清晰的代码，具有良好的标识符 - 有时被称为“自我记录”的东西 - 可以很好地说明代码正在做什么。就目前而言，这很好。评论的工作是解释为什么。

Answer 5

评论的问题是，在评论的代码发生变化甚至被删除后，它们往往会持续很长时间。

根据经验，我只评论公共API和难以理解的算法。

不要使用注释来解释你做了什么 - 这就是代码的用途，使用注释来解释你为什么这么做。

Answer 6

这个主题往往会被讨论很多，但这里的主题是我的0.02美元：

1. 我宁愿看到太多的评论而不是。任何事情都失败了，你总是可以从代码中删除多余的评论;但是，如果没有开头的话，你就无法从中得出意义。
2. 我听说有些开发人员认为其他开发人员“过度记录”（这个定义因人而异）他们的代码并不是好的开发人员。虽然说你正在更新计数器可能表明你不知道自己在做什么，但是对于你正在使用的方法中间的一些业务逻辑有一个明确的指导可能非常有用。
3. 虽然有一些优秀的开发人员可以编写非常清晰的代码而不需要注释，但是大多数开发人员都不是那么好，或者他们花费更多的时间编写代码来进行自我记录而不是他们刚才包含了几条评论。
4. 您不知道下一个人阅读您的代码的技能水平，如果您正在使用的语言结构可能会令人困惑，通常最好包含一个人可以使用谷歌教程的评论。

Answer 7

Diomidis Spinellis刚刚为IEEE专栏（quoted on his blog）写了一篇很好的专栏，概述了这个问题，并提出了一些解决方案：

  

评论时，我们总是一对   远离灾难的按键：   重述代码的功能   英语。这就是问题所在   启动。

Answer 8

应该在代码之前或函数之前写注释，以便下次查看函数时，他/她可以立即知道该代码的用途是什么。
我多次发生这样的事情，我编写代码然后忘记了它的目的。所以，我习惯在代码之前写评论。

Answer 9

我希望在评论中看到的是解释为什么一个明显且比代码中使用的方法简单得多的方法不起作用。