在问我的问题之前，让我先提供一些背景信息：
我最近加入了一个新的软件开发小组，该小组使用 Rational 工具进行配置管理，包括源代码控制和变更管理系统。除了这些工具之外，团队还有一个标准做法，即在代码中将任何代码更改作为注释记录，例如：
///<history>
[mt] 3/15/2009 Made abc changes to fix xyz
///</history>
他们对注释标准的官方目的是“注释提供从需求到代码修改的可追溯性”。
我准备提出一个论点，即这种做法是不必要和多余的；团队应该立即摆脱这个标准。
也就是说，变更管理系统是建立从需求到代码修改的可追溯性的地方，源代码控制可以通过在版本之间执行差异来提供详细的变更历史记录。签入源代码时，会注明相应的变更管理票证。解决 CM 票证后，我们会注意修改了哪些源代码文件。我相信这为所需的可追溯性提供了足够的交叉参考。
我想知道是否有人不同意我的论点。我是否错过了更改管理和源代码控制系统无法提供的注释源代码历史记录的一些好处？
对我自己来说，我一直发现这样的评论比它们的价值更麻烦：它们可能导致合并冲突，当你试图隔离两个版本之间的差异时可能会显示为“误报”，并且可能会引用代码更改此后的更改已过时。
通常（不总是，但经常）可以更改版本控制系统而不会丢失元数据。如果您要将代码移动到不支持此功能的系统，那么在转换之前编写脚本将更改历史记录转换为注释并不难。
注释允许您在代码中相关的地方找到所有更改及其原因，而无需深入研究差异和版本控制系统的复杂性。此外，如果您决定更改版本控制系统，评论将保留。
我参与了一个类似做法的大型项目，该项目曾两次更改源控制系统。没有一天我不高兴听到这些评论。
是多余的吗？是的。这是不必要的吗？不。
我一直认为代码当然应该受版本控制，并且当前源代码（您今天可以打开和阅读的源代码）应该只在现在时有效。
过去的报告是否最多包含 3 个轴并不重要，而上个月您将其更新为最多支持 6 个轴。扩展一些功能或者修复一些bug都没有关系，只要当前版本容易理解即可。当您修复错误时，只需保留已修复的代码。
不过有一个例外。如果（且仅当）固定代码对您来说看起来不如前一个不正确的代码那么直观；如果你觉得有人明天可能会来，并且仅仅通过阅读代码就想把它改回“看起来更正确”的内容，那么最好添加一条评论：“这样做是为了避免......呸呸呸。” 另外，如果背后的问题是团队文化中臭名昭著的战争故事，或者由于某种原因错误报告数据库包含有关这部分代码的非常有趣的信息，我不会觉得添加“（参见错误 ID 10005)”到解释性评论。
我突然想到的是供应商锁定。如果您曾经离开过 Rational，那么您需要确保在迁移期间维护了完整的变更历史——而不仅仅是工件的版本。
当您在代码中时，您需要知道为什么它的结构如此，因此在代码注释中。位于代码之外的工具，尽管它们可能很好，但需要在你的大脑中进行太多的上下文转换才能有用。除此之外，试图从文档和差异中逆向工程代码意图非常困难，我宁愿每天阅读一行评论。
在我处理的代码中有一个阶段，早在 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 团队也必须修复代码。该评论是一种帮助-向我保证该错误是真实的-但令人恼火。