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

Question

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

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

Answer 1

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

编辑:

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

Answer 2

在现实世界中,编程并不仅仅意味着编写代码.这意味着编写代码,让另一个程序员(或者您自己,在3个月内)可以有效地理解和维护.

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

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

• 与他的代码相关的错误率将高于他们可能的错误率,因为他忘记提及的所有这些假设和特殊情况将不断地绊倒人.(你有多少次在代码中做一些"不寻常"的事情来使某些东西发挥作用,忘记评论它为什么你这样做,然后认为它看起来像一个bug并"修复"它,只是发现你因为一个你不记得的微妙而破坏了可怕的东西？)

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

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

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

• 他没有意识到通过使用良好的变量命名,精心设计的命名前缀/约定和文档注释,他可以更好地利用他的IDE(自动完成,智能感知帮助等)和代码的神话般的省时功能.更快,缺陷率更低.

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

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

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

3)使用像我的AtomineerUtils插件或Submain的GhostDoc这样的工具,这意味着他的文档注释可以很容易地与代码保持同步.