评论总是错的 - 是对还是不对？

Question

随机地浏览了blog关于如何永远不应该阅读评论的内容，并且自己想到我读过的所有评论都是错误的，过时的，或者只是令人困惑。如果一个简单的永远不会读取评论和/或只是使用正则表达式替换模式来删除... :-) ...只是开玩笑，但真的，也许不是。至少看起来像评论和相关代码应该有时间戳。同意还是不？

仅供参考，博客似乎是由这个stackoverflow用户：Nosredna

Answer 1

不正确的评论与错误代码一样严重。如果这是一个持久性问题，我会说该项目存在严重问题。诸如PostgreSQL（在src目录中未压缩的94M）等大项目依赖于准确的注释来帮助程序员快速理解事物。他们也非常重视评论。

编辑：

另外，如果你无法总结你的功能在做什么，那么谁可以呢？编写完一个函数后，为它编写注释可能是一个测试，你完全理解正在发生的事情。如果你脑子里的事情仍然有些混乱，当你尝试写评论时，它会变得非常明显。这是一件好事，它显示了仍然需要处理的事情。

Answer 2

在现实世界中，编程并不仅仅意味着编写代码。这意味着编写代码，以便其他程序员（或您自己，在3个月内）可以有效地理解和维护。

任何程序员都告诉你注释/文档不值得花时间编写/维护它们有很多问题：

• 他的长期工作率（以及任何必须使用他的代码的同事的工作率）将低于其可能的。人们将浪费大量时间来理解可以用快速句子描述的代码。

• 与他的代码相关的错误率会比他们更高，因为他忘记提及的所有这些假设和特殊情况会不断地让人们吵架。 （你有多少次在代码中做一些“不寻常”的事情来使某些东西发挥作用，忘记评论它为什么你这样做，然后认为它看起来像一个bug并“修复”它，只是发现你因为一个你不记得的微妙而破坏了可怕的东西？）

• 如果他懒得写下他的代码如何工作或应该如何使用，他还会采取什么其他捷径？他是否懒得检查空值并处理异常？他是否关心他的界面是否一致？如果方法/变量的基本含义发生变化，他是否会重构方法/变量的名称？通常糟糕的评论只是冰山一角。

• 许多这样的程序员过于专注于“酷炫的东西”（比如优化代码中的每个最后一个循环，或者找到一种聪明的方法将一段看似简单的代码混淆成一个令人难以置信的模板）来理解商业现实（例如，他可能无法让他的代码工作并运到最后期限，因为他专注于从中挤出不必要的性能而不仅仅是完成工作）

• 他的设计有多好？当我写下文档/评论时，我会完成大部分的设计和思考。通过尝试向读者解释我的评论，我清除了许多我不会错过的缺陷和假设。我甚至会说我经常写评论（我的意图/设计），然后用它们同步代码。在大多数情况下，如果我的代码中存在错误，则代码错误而不是注释。

• 他没有意识到通过使用良好的变量命名，精心设计的命名前缀/约定和文档注释，他可以更好地利用他IDE的神奇时间节省功能（自动完成，智能感知帮助）等等，并且编码速度更快，缺陷率更低。

从根本上说，他可能不明白如何写好评：

1）评论应该充当一大块代码的快速阅读摘要。我可以阅读一个简短的文本行，而不必弄清楚许多代码行的含义。如果您发现自己正在阅读代码以进行导航，则评论很差。我阅读了注释以导航和理解代码，当我真正需要处理它的特定位时，我只阅读代码本身。

2）方法/类注释应该向调用者描述使用该类需要知道的所有内容，而不必查看代码实现的“黑盒子”。他们将能够快速掌握如何使用类/方法，并了解API提供的所有副作用和“契约” - 什么可以为null，必须提供什么，以及抛出哪些异常等。如果你必须阅读代码来获得它，那么它要么被严重封装，要么被严重记录。

3）使用我的AtomineerUtils插件或子网GhostDoc等工具，这意味着他的文档评论可以很容易地与代码保持同步。

Answer 3

代码注释有时可能非常宝贵。很多时候，我一直在努力确定代码的意图失败。对于任何复杂性的代码，如果作者记录其意图，则可能会有所帮助。当然，写得好的单元测试也可以使意图明确。

Answer 4

我个人并没有写很多评论，但我写的常见评论类型是：

• （草图）证明我的代码是正确的
• 解释为什么不做那件显而易见的事情（例如：需要优化，我所说的API是令人震惊的误导，“显而易见的事情”导致了一个微妙的错误）
• 输入边缘情况的描述，需要特殊处理，从而解释了出现特殊处理代码的原因
• 对要求或规范的引用，该要求或规范规定了由特定代码行实现的行为
• 对所采取的一系列步骤的顶级描述:(“首先获取输入”，“现在剥离包装器”，“最后解析它”），如果每个调用的函数名称都不需要步骤在上下文中是精心选择和明确的，但我不打算为通用函数编写一个do-nothing包装器，只是为一次使用提供更具体的名称
• 自动提取的文档。这是一个很大比例的评论量，但我不确定它“真的很重要”。
• 可以成为文档化界面的一部分的东西，但不是因为它们将来可能需要更改，或者因为它们是外部人员不需要的内部帮助程序。因此，对于实现者而言，有用但不是对用户有用。私有类不变量包含在此中 - 您是否真的想要在每次要依赖“此成员非空”或“大小不大于容量”或“访问此成员”时读取整个类必须同步“？最好在分配成员之前检查成员的描述，看看你是否被允许。如果有人没有纪律，以避免打破一个明确评论的不变量，那么，难怪他们的所有评论都是错误的......

其中一些事情是通过综合测试来处理的，因为如果测试通过然后代码是正确的（哈哈），如果你也打开了测试代码，那么你可以看到特殊的输入案例，如果有的话傻瓜隐藏评论，犯了我原来做的同样的错误，并重构我的代码做明显的事情，然后测试将失败。这并不意味着评论在阅读代码的上下文中不会处理更好。在这些案例中，没有一个是阅读评论而不是阅读代码，它们旨在突出重要但不明显的内容。

当然，对于自动文档，单独查看文档是完全合理的，也可能更有用。

调试时，与进行更改相反，方式让代码解释更有价值。注释不太有用，特别是那些私有不变量，因为如果你正在调试，那么编写代码+注释的人有可能犯了错误，因此注释可能是错误的。从好的方面来说，如果您看到的评论不能反映代码的作用，那么您就有可能找到错误。如果您只是看到代码的作用，可能需要一段时间才能意识到代码的作用并不是它应该做的。

有时，良好的命名会在替换评论方面发挥很大作用。但是，如果名称错误，名称可能会像评论一样具有误导性。而且，说实话，通常名字至少有些误导或含糊不清。我怀疑该博客文章的作者是否会将所有名称替换为“var1，var2，func1，func2，class1，class2 ......”，以确保他们不被原作者的注意力分散代码的意图不正确。我并不认为说“评论总是错误的”比说“变量名总是错的”更为真实。它们是由同一个人同时写成的。

Answer 5

有些评论很有用，其他评论则没有。

是的，评论和代码应该加上时间戳，但是你不应该自己加时间戳。您的源代码管理系统应该为您管理，您应该能够访问此信息（例如，使用cvs annotate或svn blame）。

Answer 6

评论为什么你正在做某事而不是你在语法上做了什么。