配置管理 - 代码注释中的历史记录

Question

在提问之前，让我简单介绍一下背景信息：

最近我加入了一个使用Rational工具进行配置管理的软件开发团队，包括源代码控制和变更管理系统。

除了这些工具外，团队还有一个标准做法，就是将任何代码更改都作为注释写在代码中，例如：

///<history>
   [mt] 3/15/2009  Made abc changes to fix xyz
///</history>

他们官方的评论标准目的是“评论提供从需求到代码修改的可追溯性”。

我准备提出一个观点，认为这种做法是不必要和多余的；团队应该立即摒弃这一标准。

换言之，变更管理系统是建立从需求到代码修改的可追溯性的地方，源代码控制可以通过在版本之间执行差异来提供详细的更改历史记录。当源代码被检入时，相应的变更管理票据会被记录下来。当变更管理票据被解决时，我们会记录哪些源代码文件被修改。我相信这为所需的追溯性提供了足够的交叉参考。

我想知道是否有人不同意我的观点。我是否错过了注释源代码历史记录的一些优点，这些优点变更管理和源代码控制系统无法提供？

- mtazva

---

这让我想起了这个宝石般的源代码：http://telusplanet.net/public/stonedan/source.txt - 我认为它本身就说明了一切。 - Tamas Czinege

这似乎是 http://stackoverflow.com/questions/638912/638952 的重复。 - John Saunders

Answer 1

对于我个人而言，我总是觉得这样的评论比它们所值得的麻烦更多：它们可能会导致合并冲突，在您尝试隔离两个版本之间的差异时可能会出现“错误的正面”，并且可能引用自后来的代码更改已经过时的代码更改。

通常（不总是，但通常）可以在不丢失元数据的情况下更改版本控制系统。如果您将代码移动到不支持此功能的系统中，则在切换之前编写脚本将更改历史记录转换为注释将不难。

- dbreslau

---

可能引用了后来已经过时的代码更改，这是迄今为止最令人恼火的事情。我不明白为什么人们在添加某些内容时会添加注释，但却不想在删除某些内容时做同样的事情！ - matt b

这是我的主要关注点，除了由于长期更改函数而导致的膨胀。我认为源代码应该只记录其当前状态。所有其他文档都应该放在其他地方（消除噪音！）顺便说一句，到目前为止，我的最喜欢的注释是：[ab] 1/1/2005 创建函数。 - mtazva

Answer 2

评论允许您在代码中找到所有更改及其原因，而无需深入挖掘差异和版本控制系统的复杂性。此外，如果您决定更改版本控制系统，评论将保留。

我曾经参与过一个类似实践的大型项目，已经两次更改了源代码控制系统。每天我都很高兴有这些评论存在。

它是否多余？是的。 它是否不必要？不是。

- Julian Aubourg

---

你可以在任何合理的版本控制系统中使用注释工具。 - Eugene Morozov

直到你改变版本控制系统并且失去了那些注释。 - Julian Aubourg

解决真正的问题，例如将旧版本控制系统中的所有变更控制注释导入新版本控制系统。如果新系统无法执行此操作，则为什么要购买新系统？ - Ian Ringrose

Answer 3

我一直认为代码应该在版本控制下，而且当前的源代码（你今天可以打开和阅读的那个）只应该在现在时态下有效。

过去报告最多可能有3个轴，上个月您更新了它以支持多达6个轴，或者您扩展了某些函数或修复了某些错误，都不重要，只要当前版本能够轻松理解。修复错误时，只需保留已修复的代码。

然而，有一个例外。如果修复后的代码看起来比之前的不太直观，如果你觉得有人明天可能会来，仅仅通过阅读代码就会想把它改回“更正确”的状态，那么添加注释是好的：“这样做是为了避免......blah blah blah。”此外，如果问题背后是团队文化中的一个臭名昭著的战争故事，或者由于某种原因，缺陷报告数据库包含关于这部分代码的非常有趣的信息，我认为在说明注释中添加“（请参见Bug Id 10005）”并不算错误。

- Daniel Daranas

---

我完全赞同，丹尼尔。"这样做是因为..." 这样的注释应该被视为标准代码文档注释，而不是历史性注释，并且绝对是必要的。当我打开源代码进行更改时，我关心的是代码执行的操作，而不是过去的情况。 - mtazva

Answer 4

我想到的一个问题是供应商锁定。如果你曾经离开 Rational，你需要确保在迁移过程中完整的更改历史记录得以维护，而不仅仅是工件的版本。

- JohnW

---

这不管怎么说都有点问题，特别是如果你计划支持软件的旧版本。我认为更重要的是在源代码中正确记录当前版本代码正在做什么。如果我想看它以前是怎样的，那似乎就是源代码控制发挥作用的地方。 - mtazva

Answer 5

当你在编写代码时，你需要知道为什么它被构建成那样，因此需要进行代码注释。虽然外部工具可能很好用，但它们需要你的大脑进行太多的上下文转换才能派上用场。此外，试图从文档和差异中反向工程代码意图是非常困难的，我宁愿每天阅读一行注释。

- MrTelly

---

要明确一点 - 我所说的并不是与当前代码集相关的注释。我所说的是记录更改历史的注释。我同意任何不足以“自我记录”的代码都应该有有用的注释。我的担忧是在源代码中包含整个函数的历史记录。 - mtazva

Answer 6

我所从事的代码在1994-96年期间有一个阶段，那时候有一种倾向是在文件顶部插入变更历史注释。这些注释现在已经毫无意义和用处，当我编辑包含此类注释的文件时，我会执行许多标准清理操作之一，即将它们删除。

相比之下，在更改位置处带有错误编号的某些注释通常解释了为什么荒谬的代码是这样的，这些注释可能非常有帮助。错误编号为您提供了其他信息查找的地方，并指出了罪犯（或受害者-因情况而异）。

另一方面，像这样的项目-真实的;上周清理干净-让我咬牙切齿。

    if (ctab->tarray && ctab->tarray[i])
#ifndef NT
      prt_theargs(*(ctab->tarray[i]));
#else
      /* Correct the parameter type mismatch in the line above */
      prt_theargs(ctab->tarray[i]);
#endif /* NT */

NT团队正确地处理了这个调用。我不明白他们为什么认为这是一个特定于平台的修复。当然，如果代码现在使用原型而不是无参数声明，则Unix团队也必须修复代码。这个注释很有帮助-确保我这个错误是真实存在的-但令人沮丧。

- Jonathan Leffler