什么时候评论"太多",何时他们还不够？

Question

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

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

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

Answer 1

这已被讨论过死亡.

我只想指出杰夫阿特伍德关于这个主题的精彩帖子,它正好击中了头部.

Answer 2

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

Answer 3

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

在一般情况下,只有非常棒的代码大师才会编写这样的代码.我们其他人凑齐了一些有效的东西.

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

Answer 4

"其中一位负责人指示他的开发人员不要使用评论,因为他们过于"过时",而其他几位开发人员表示,他们从不使用评论,因为他们觉得他们所做的只是混乱了代码."

如果我听过一个开发人员,我就是这样说话,我会纠正他们.如果我没有必要的等级来纠正它们,我会离开这份工作.

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

Answer 5

这个话题经常被讨论，但这里是我关于这个话题的 0.02 美元：

1. 我宁愿看到太多评论，也不愿看到评论不够。如果出现任何问题，您可以随时从代码中删除多余的注释；然而，如果一开始就没有意义，你就无法从中获得意义。
2. 我听说一些开发人员认为其他“过度记录”（这个定义因人而异）的开发人员不是优秀的开发人员。虽然说您正在更新计数器可能表明您不知道自己在做什么，但对您正在处理的方法中间的一些业务逻辑有一个清晰的指南可能非常有用。
3. 虽然有一些优秀的开发人员可以编写不需要注释的极其清晰的代码，但大多数开发人员都不是那么好，或者他们花更多的时间编写自我文档化的代码，而不是只包含一些代码评论。
4. 您不知道下一个阅读您代码的人的技能水平，并且如果您使用的语言结构可能令人困惑，那么通常最好添加一条评论，以便其他人可以使用它来搜索教程。