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

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

我最近加入了一个新的软件开发小组，该小组使用Rational工具进行配置管理，包括源代码控制和变更管理系统。 除了这些工具之外，团队还有一个标准做法，即将任何代码更改作为注释记录在代码中，例如：

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

///
[mt]3/15/2009对修复xyz进行了abc更改
///

注释标准的官方目的是“注释提供从需求到代码修改的可追溯性”

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

也就是说，变更管理系统是建立从需求到代码修改的可追溯性的地方，而源代码控制可以通过执行版本之间的差异来提供详细的变更历史。签入源代码时，会记录相应的更改管理票证。解析CM票证时，我们会注意修改了哪些源代码文件。我相信这为期望的可追溯性提供了充分的交叉参考

---

我想知道是否有人不同意我的论点。我是否错过了更改管理和源代码控制系统无法提供的注释源代码历史的一些好处

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

我曾在一个大型项目中工作，该项目具有类似的实践，曾两次更改了源代码管理系统。没有一天我对这些评论感到不高兴

它是多余的吗？对

---

没有必要吗？不。

我突然想到的是供应商锁定。如果您曾经离开Rational，您需要确保在迁移过程中维护完整的更改历史，而不仅仅是工件的版本。

当您在代码中时，您需要知道为什么它是这样结构的，因此在代码注释中。代码之外的工具，虽然可能很好，但需要在你的大脑中进行太多的上下文转换才能发挥作用。除此之外，试图从文档和差异中逆向工程代码意图非常困难，我更愿意每天读一行注释。

对于我自己，我总是发现这样的注释比它们的价值更麻烦：它们可能会导致合并冲突，当您试图隔离两个版本之间的差异时，可能会显示为“误报”，并且可能引用后来被更改淘汰的代码更改

---

在不丢失元数据的情况下更改版本控制系统通常是可能的（并非总是，但通常是）。如果您要将代码移动到一个不支持此操作的系统，那么在切换之前编写脚本将更改历史转换为注释并不困难。

我所处理的代码中有一个阶段，在1994-96年的时间框架内，倾向于在文件顶部插入更改历史记录注释的位置。这些注释现在毫无意义，毫无用处，我在编辑包含这些注释的文件时执行的许多标准清理之一就是删除它们

相比之下，在进行更改的位置也有一些带有bug编号的注释，通常解释了为什么代码如此荒谬。这些可能非常有用。错误编号让您在其他地方查找信息，并指出罪魁祸首（或受害者-情况各不相同）

另一方面，像这样的物品——正品；上周打扫干净了，让我咬紧牙关

    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 */

---

新界队接到正确的电话；我无法理解为什么他们认为这是一个特定于平台的修复。当然，如果代码以前使用原型而不是无参数声明，那么Unix团队也必须修复代码。这个评论对我很有帮助，让我确信这个bug是真实的，但令人恼火。

我一直认为代码当然应该在版本控制下，当前的源代码（您今天可以打开并阅读的源代码）应该只在现在时有效

在过去，一个报表是否最多可以有3个轴并不重要，上个月您将其更新为最多支持6个轴。无论您是扩展了一些功能还是修复了一些bug，只要当前版本易于理解就行。修复bug时，只需保留已修复的代码

---

但也有例外如果（且仅当）固定代码对您来说不如前一个错误代码直观；如果您觉得明天可能会有人来，仅仅通过阅读代码，就想把代码改回“似乎更正确”，那么最好添加一条评论：“这样做是为了避免……诸如此类。”此外，如果背后的问题是团队文化中臭名昭著的战争故事，或者，如果出于某种原因，错误报告数据库包含关于这部分代码的非常有趣的信息，我不会发现在解释性注释中添加“（请参见错误Id 10005）”是不正确的。

这让我想起了这段源代码：-我认为它本身就说明了这一点。这似乎是对的重复。“可能会引用后来被更改淘汰的代码更改“到目前为止，这是最烦人的。我不明白为什么人们在添加某些内容时会添加注释，但在删除某些内容时却不会这样做！这是我最关心的问题，除了长期以来对函数的更改造成的膨胀之外。我认为源代码应该只记录它的当前状态。所有其他文档都属于其他地方（消除噪音！）顺便说一句，到目前为止我最喜欢的cmt是：