配置管理 - 代码注释中的历史答案

【问题标题】：Configuration Management - History in Code Comments配置管理 - 代码注释中的历史
【发布时间】：2009-03-16 01:39:15
【问题描述】：

在问我的问题之前，让我先提供一些背景信息：

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

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

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

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

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

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

【问题讨论】：

这让我想起了这个源代码的瑰宝：telusplanet.net/public/stonedan/source.txt - 我认为它不言自明。
这似乎是 stackoverflow.com/questions/638912/638952 的副本。

标签： coding-style configuration-management change-management

【解决方案1】：

就我自己而言，我一直发现此类 cmets 带来的麻烦多于其价值：它们可能导致合并冲突，在您尝试隔离两个版本之间的差异时可能会显示为“误报”，并且可能参考已被后来的更改废弃的代码更改。

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

【讨论】：

“可能会引用已经被后来的更改废弃的代码更改”这是迄今为止最烦人的。我不明白为什么人们在添加某些东西时会添加 cmets，但是当他们删除某些东西时不要想这样做！
这是我最关心的问题，除了函数的长期更改历史造成的臃肿。我相信源代码应该只记录它的当前状态。所有其他文档都属于其他地方（静音！）顺便说一句，到目前为止我最喜欢的 cmt 是：[ab] 1/1/2005 Created function

【解决方案2】：

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

我曾参与过一个类似做法的大型项目，该项目曾两次更改源代码控制系统。没有一天我不高兴拥有这些 cmets。

它是多余的吗？是的。这是不必要的吗？没有。

【讨论】：

您可以使用任何健全的 VCS 中提供的注释工具。
直到您更改版本控制系统并松开所述注释。
解决真正的问题，例如将旧版本控制系统中的所有变更控制cmets导入新版本控制系统。如果新系统不能做到这一点，你为什么要买新系统？

【解决方案3】：

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

报告过去是否最多可以包含 3 个轴，而上个月您将其更新为最多支持 6 个轴，这并不重要。扩展一些功能或者修复一些bug都没有关系，只要当前版本容易理解即可。当你修复一个错误时，只需留下修复的代码。

不过有一个例外。如果（且仅当）固定代码对您来说不像前一个不正确的代码那么直观；如果你觉得有人明天可能会来，并且仅仅通过阅读代码就想把它改回“看起来更正确”的内容，那么最好添加一条评论：“这样就完成了避免的方法...等等等等。” 另外，如果背后的问题是团队文化中臭名昭著的战争故事，或者由于某种原因错误报告数据库包含有关这部分代码的非常有趣的信息，我认为在解释性评论中添加 "(see Bug Id 10005)" 是不正确的。

【讨论】：

我完全同意，丹尼尔。 “这样做是因为......”符合标准的代码文档注释，而不是历史注释，并且是绝对必要的。当我开源代码进行更改时，我关心的是代码做了什么，而不是它曾经做什么。

【解决方案4】：

让我想到的是供应商锁定。如果您曾经离开过 Rational，则需要确保在迁移期间维护完整的更改历史记录——而不仅仅是工件的版本。

【讨论】：

这难道不是个小问题吗？至少，如果您打算支持任何旧版本的软件。我认为正确记录当前版本的代码在源代码中的作用更为重要。如果我想看看它曾经做什么，那似乎是源代码控制步骤

【解决方案5】：

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

【讨论】：

要清楚 - 我不是在谈论与当前代码集相关的 cmets。我说的是记录更改历史的 cmets。我同意任何不够“自我记录”的代码都应该有有用的 cmets。我担心的是在源代码中拥有函数的整个历史。

【解决方案6】：

在我处理的代码中有一个阶段，早在 1994-96 年的时间框架内，就有在文件顶部插入更改历史记录 cmets 的趋势。这些 cmets 现在毫无意义和无用，我在编辑包含此类 cmets 的文件时执行的许多标准清理工作之一就是删除它们。

相比之下，也有一些cmets在改动的位置有一个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 */

NT 队的判罚是正确的；为什么他们认为这是特定于平台的修复程序超出了我的范围。当然，如果代码之前使用原型而不是无参数声明，那么 Unix 团队也必须修复代码。该评论是一种帮助 - 向我保证该错误是真实的 - 但令人恼火。

【讨论】：