Question

天儿真好，

受到我在回复this question时对Perl regexp发表评论的评论的启发，我想知道以下内容。

当您处理旧的，古老的，血腥的古代代码时，您是否更新了与代码不同步的注释，或者您只是更新代码并忽略已经从实际情况“向外”的评论目前的代码？

我想基本接近“broken window”综合症的内容？

BWS基本上说人们只是说“填充它”，如果他们发现那些已经参与了相关系统的人并不关心修复这些类型的错误，那么就不要小心修复那里的错误。的东西。一个完全普遍的心态恕我直言！

我有兴趣看看其他人“在煤矿面前”做什么。

欢呼声，

Answer 1

我绝对会修复不好的评论。

有时只是删除它们以免误导。

更好的是，我更喜欢重构代码，因此评论不是必需的 - 自我记录代码比评论更好，因为它不能过时。

Answer 2

最近我开始关注更多Bob叔叔的Clean Code建议，我试图将注释转换为函数，这些函数将注释代码包含（提取）在一个至少与它替换的注释一样有意义的函数中。

Answer 3

如果可以，我总是尝试更新它们，或者至少添加一个注释，表明它们可能是错误的。这是一个值得投资的少量时间。

我经常做的另一件事是添加任何相关的错误编号，以及这些编辑产生了什么影响 - 这对于了解更多信息总是有用的。

Answer 4

如果评论是必要的，我会更新它，否则我会尝试将代码更改为我可以直接删除评论并让代码文档本身。

Answer 5

当我发现无用的GhostDoc生成的评论时，我有时会删除它们：

这些评论的目的是什么？

/// <summary>
/// Saves the form properties.
/// </summary>
/// <param name="form">The form.</param>
/// <param name="propertyNames">The property names.</param>
void SaveFormProperties(Form form, string[] propertyNames);

Answer 6

作为一个相当新鲜的程序员，我并不像我自己那样在旧代码上工作太多，但我试着每隔一段时间回过头来确保我自己的评论与事实相当接近。留下没有正确描述代码功能的注释是没有意义的。

那说如果你赶时间，那么浪费太多时间更新评论是没有意义的。添加一个“这已经过时”的效果解决了保留导航的问题，而不会使其准确无误。

Answer 7

我会修复评论。

为什么不解决任何问题？如果您了解正在处理的代码，那么评论应该是最简单的修复。显然，如果你已经麻烦钻研它，那么代码应该比你发现的更好。

我甚至认为，在多人接触代码的群组中，评论可以被视为与代码本身一样重要。没有它，思想的交流就会被打破。

在实践中，我可能不会发表评论。很难承认你或其他人可能会在你的“杰作”中挖掘。

Answer 8

如果您的文档是根据评论生成的（我强烈推荐这一点）那么是的，我保持评论与代码的细致同步。

Answer 9

如果我发现问题，我会立即修复评论，并且可能会记下改进代码所需的内容。

如果我被公共汽车击中，那么代码对于我的快速，尖锐的关注来说就更好了。

然后，如果我有时间，我会对代码本身进行排序（修复它通常需要耗时的回归测试）。如果没有，我会把它留下一天，但至少我知道当我有时间回到它时，问题是什么。

Answer 10

对于告诉任何未来的维护者或程序员，代码正在做什么或为什么以这种方式这样做是非常有用的。

如果您在不更新评论的情况下更改代码，那么充其量就会让人感到困惑，如果不是完全误导的话。

Answer 11

我努力遵循童子军规则，让代码比我发现的更干净。我将查看更新注释或重构代码以避免评论的需要。我发现通常最好不要发表评论，而不是发表不正确的评论。

Answer 12

如果项目受版本控制（现在应该是，但你永远都不知道）并且有大量过时的评论，我会删除大块并留下一个新的评论，我的效果我删除了一大堆旧的评论，这些评论似乎不再具有启发性，我提交了一条说明，我已经删除了过时的评论。

最终，我会删除提及删除的评论，或将其替换为适用于新代码的评论。

然而，在一个由一群程序员维护的系统中，改变旧的，被认为无意义的评论是不利的：

评论不再作为评论了！ 它们是熟悉代码的程序员的标志。它们是具有里程碑意义的评论，而不是解释性评论。

程序员实际上可能会在地标评论中搜索关键字以导航文件。

如果您删除了具有里程碑意义的评论，甚至更改了它们，您可能会大大减慢使用它们来浏览文件的程序员的速度。你正在弄乱那些与代码有长期关系的人的心理地图，你会造成更多的伤害而不是好处。大脑是一件有趣的事情。在一个时髦的评论中记住一个单词或短语可能比一个方法的名称容易得多。

在我看来，如果评论与代码非常过时，您应该了解原因。假设其他程序员不关心代码，似乎令人难以置信地推测。也许他们这样做，也许他们没有。如果您正在接管一个离开的人的文件，并且您拥有明确的所有权，请继续挖掘！如果你是那些已经在代码上工作了20年的人中的新人，还有其他证据表明他们做关心代码，也许你会遗漏一些东西。

这类似于重新格式化的问题 - 改变间距，改变开口括号的位置等等。这在很大程度上取决于所有权。你打算把文件放在你身边的那个人的20倍吗？或者经常1/20？如果是后者，你真的想让他迷惑吗？

所以要确保这不是你正在做的事情，或者明天你可能会听到有人喊叫，“这到底有什么功能？”

Answer 13

我会修复评论。我看到一些答案说，如果评论过时，他们会重写代码。我只是因为评论不好而重写工作代码似乎很荒谬。如果你的工作足够重要，这种行为甚至会让你被解雇。

Answer 14

我总是修复评论 - 主要是因为我通常是处理一段代码的人。对我来说，这可能是一个类似OCD的东西，但我只是喜欢我正在努力寻找的代码 - 好的变量名，格式化（现在不是现代IDE的问题）和评论。

我不相信代码可以“重构到它自我记录的程度”。它可以重构到只需要函数，过程，成员变量，类等的注释，因为每个函数调用每个只有1-5行。来自Lisp背景我喜欢通过分解编程 - 更简单，可测试，更容易证明正确。

Answer 15

我不修复坏评论。我只是删除它们。（或者用一个短划线替换它们作为评论。）一般来说，截止日期已经过时，所以我可能花一秒钟来选择，然后删除一个不好的评论，但花30秒或更长时间来重写它将是浪费时间。（而且浪费你的注意力。）一旦截止日期过去，事情就会变得更加放松，此时通常的代码审查会放回一些新的评论。

但话说回来，你必须先注意到不好的评论。在大多数情况下，经常使用这样的旧代码文件而不进行仔细检查。而且他们经常被证明是在工作，所以我为什么要查看评论？

您是否更新了错误的古代代码注释？

15 个答案: