过时的评论是都市神话吗？

我不断看到人们声称“评论趋于过时”。问题是，我认为我在整个职业生涯中可能已经看到两三个过时的评论。单独的文档中过时的信息一直在发生，但是根据我的经验，代码本身中过时的注释非常少见。

我刚刚和谁在一起很幸运吗？某些行业是否比其他行业更容易出现此问题？您是否有看到最近过时评论的具体示例？还是过时的评论更多是理论问题而不是实际问题？

不断地

我真的不敢相信我是唯一在过时和误导性评论中游刃有余的人。在偶然的情况下，这有助于理解：

这可能最重要地取决于代码的年龄。下一个因素将是人员流动。

我从事研发和维护工作。R＆D是新的代码，通常来说有些偏离常规。我的许多同事相信，在尝试没有图书馆可用的东西时，请多加注解。由于注释与代码的比率比正常的比率高，因此存在更多不同步的机会。

维护代码...我是系统的活跃维护者，该系统已经使用了10年以上，而另一个系统是5年以上。正如您所期望的那样，使用10年的代码和注释非常糟糕。十多年来，您在代码库中获得了很多帮助，没有人知道整个过程如何工作。使用5年的代码和注释非常不错，因为团队的人员流失率非常低。

我几乎提供所有服务，甚至我们的产品都是针对特定客户量身定制的。

具体示例：

• 描述特定方法的性能改进的注释，例如避免复制内存。当奔腾2中的高端计算机具有MB的RAM时，这很重要，但现在几乎没有问题。

• 待办事项

• 复制粘贴的代码块，包括注释。评论在其原始位置可能很有意义，但在这里几乎没有任何意义

• 在注释掉的代码之上添加注释块（谁知道其中已有多少年了）。

在所有这些中，您看到了一种趋势，就是不将注释和代码保持在与软件相同的级别。IDE和基本的开发人员习惯对此无济于事，我的眼睛已经训练过，可以超越它们。我认为，在绿地和活跃项目中避免过时的评论相对便宜。如果您可以保持较高的代码/注释比率，则使它们保持最新并不重要。当您为生产系统中的错误修复预算了x个小时的预算时，要证明减少这些工作的难度会有些困难。

“评论趋于过时。”

我已经看到这种情况经常发生，足以知道这可能是一个问题。

问题是，我认为我在整个职业生涯中可能已经看到两三个过时的评论。

我认为，在每个人都充分注意并维护评论的环境中工作应该是完全可能的。查看正在编辑的代码附近的注释并在适当时更新它们，这只是一小笔额外的工作。如果评论距离太远，以至于您没有立即注意到它们，那么它们无论如何都是不好的评论，因此不应该首先添加（或至少不添加）。

此外，通常伴随着评论趋于过时的陈述，随之而来的陈述是，这降低了可读性并使人们感到困惑。这是我还没有经历过的事情。每次遇到过时的注释时，我都会清楚地看到发生了什么变化，并且只需付出一些额外的努力就可以相应地更新注释以表示较新的代码。

Roehm等人的最新研究。2012年观察到以下情况：

[28名参与者中，有21名]报告称他们从源代码和内联注释中获取了主要信息，而只有四名参与者表示文档是其主要信息来源。

这符合您的怀疑，即代码本身中的注释通常仍被认为非常有用。这表明应该在过时的文档和过时的注释之间划清界线。

_{Roehm，T.，Tiarks，R.，Koschke，R.，＆Maalej，W.（2012年6月）。专业开发人员如何理解软件？在《 2012年国际软件工程大会》（第255-265页）中。IEEE出版社。}

过时的评论是工作的味道。这就像已经过时或被忽略的单元测试一样，它表明曾经在商店中活跃的良好流程正在退化为牛仔编码。花时间做正确的事情的正确的“工程文化”已经崩溃。该项目/公司可能会陷入技术债务。

简而言之，是的，您很幸运。如果您到目前为止在职业生涯中碰巧拥有一连串经营良好的商店，那么很有可能看不到这么多。但是在更典型，经营不善的商店中，这与其他混乱情况平行。

注释就像测试一样，它们在最新时非常有用，但如果没有，则可能更难理解代码。

如果您从未看到过时的评论，那么您很幸运。

我使用过的大多数代码库都充满了过时的注释，通常我完全不理会注释，因为它们通常是混乱的源头而不是帮助。

过时的注释通常出现在JavaDoc中：

• 列出不再存在的参数
• 不解释所有参数（稍后可能添加缺少的参数）
• 例外情况类似。

此外，有时，当大多数性能方面的考虑往往比代码本身更快时，陈旧的注释会声明诸如“在此处执行以提高性能”之类的事情。

我会不时地处理过时的评论。这当然不是都市神话。人们在最坏做法列表中提到它不是因为它经常打击您，而是因为当它打击您时，通常会花费您大量的时间和精力。

在我们的代码库中，大多数过时的注释是由在调用附近而不是在方法声明附近使用（反）模式描述方法行为引起的。当有人将一长段代码提取到一个方法中时，就会发生这种情况，该方法此刻仅被调用一次，然后注释该方法调用。因此，您最终会得到如下结果：

featureList = GetFeatures();

// Sorting features and deleting empty ones from the list...
ProcessFeatures(featureList);

并且该方法在下面的某处声明，没有注释。多年来，人们一直在使用这些方法来处理规格更改和修复错误，最终您最终得到的方法无法对列表进行排序，并且在找到空功能时会抛出异常。因此，以上注释是过时的注释，最终将使您花费一些时间在调试器中。这些确实在某些代码库中发生。

问问自己这个。您是否曾经更改过一行代码，却没有更改相关注释或添加新注释？

我处理了许多旧代码，有时注释甚至不相关。

在大多数情况下，我的经验与您的经验相符，但是我遇到了一种情况，在整个代码库中都是如此。该应用程序是几年前由一家咨询公司编写的，不再与客户保持“良好关系”。

该公司在注释代码方面做得非常出色，但是自从最初的交接以来一直维护它的程序员是“仅更改绝对需要更改的内容”心态的一部分，这本身并不坏。不幸的是，他们对注释也保持同样的态度，随着时间的推移，导致注释和代码之间的巨大脱节。

我看不到太多的过时的描述性评论，但是我确实看到了很多已经存在多年的TODO评论了。我希望他们像时间囊，并说出这样的话：

//TODO: In 15 years AND NO SOONER... actually implement this method.

我从事的最后3个项目我花了几天时间，每个项目都从代码库中删除了过时，误导且仅是无用的注释。在可能的情况下，我将其替换为更适当的注释，但通常，这只是删除注释并继续前进的问题。

我几乎在从别人手中接过的每个代码库上都做过同样的事情，通常是在一段时间不使用它并且原始所有者早已离开和/或不愿或无法做适当的交接之后。

可能是使用评论的减少。有多少人的代码合格？首先，实际上必须有人添加评论以使其过时。其次，必须更改注释的代码。不确定是否有大量代码合格。

您只需要依靠一个不好的注释就可以破坏大量的应用程序，并浪费大量时间。

在组织大量代码的组织中，很难保持注释同步。理解正在发生的事情的最好方法是使用绘制您正在使用的模块的控制流程图的软件。这是保持了解软件功能的唯一方法。