Question

在提出我的问题之前，让我先提一下背景资料：

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

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

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

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

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

我想知道是否有人不同意我的观点。我是否遗漏了注释源代码历史的一些好处，即管理和源代码控制系统无法提供变更？

Answer 1

对于我自己，我总是发现这样的评论比它们的价值更麻烦：它们可能导致合并冲突，当你试图隔离两个版本之间的差异时，它可能显示为“误报”，并且可能参考代码更改已被以后的更改废弃。

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

Answer 2

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

我参与了一个类似实践的大型项目，该项目已经两次改变了源控制系统。没有一天我不高兴收到这些评论。

这是多余的吗？是。没必要吗？否。

Answer 3

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

如果报告在过去和上个月最多可以有3个轴，则更新它以支持最多6个轴无关紧要。只要可以轻松理解当前版本，扩展某些功能或修复一些错误并不重要。当您修复错误时，只需保留固定代码。

但有一个例外。 如果（并且仅当）固定代码看起来不像以前那么不正确;如果你觉得有人可能会在明天来，并且只是通过阅读代码，试图将其改回“看起来更正确”，那么添加评论是很好的：“这是完成的避免......等等等等。“此外，如果背后的问题是团队文化中臭名昭着的战争故事，或者由于某种原因，错误报告数据库包含有关此部分代码的非常有趣的信息，我不会发现将“（参见Bug Id 10005）”添加到解释注释中是不正确的。

Answer 4

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

Answer 5

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

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团队也必须修复代码。评论是一个帮助 - 向我保证这个错误是真实的 - 但令人生气。

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

6 个答案: