配置管理 - 代码注释中的历史记录
在提出我的问题之前，让我先介绍一些背景信息：
我最近加入了一个新的软件开发小组，该小组使用 Rational 工具进行配置管理，包括源代码控制和变更管理系统。 除了这些工具之外，团队还有一个标准做法，即在代码中将任何代码更改标记为注释，例如：
///<history>
[mt] 3/15/2009 Made abc changes to fix xyz
///</history>
他们制定注释标准的官方目的是“注释提供从需求到代码修改的可追溯性”。
我正准备提出一个论点，认为这种做法是不必要和多余的； 团队应该立即废除这个标准。
也就是说，变更管理系统是构建从需求到代码修改的可追溯性的地方，源代码控制可以通过在版本之间执行差异来提供详细的变更历史记录。 签入源代码时，会记录相应的变更管理票证。 当 CM 票证得到解决时，我们会记录哪些源代码文件被修改。 我相信这为所需的可追溯性提供了足够的交叉引用。
我想知道是否有人不同意我的观点。 我是否错过了更改管理和源代码控制系统无法提供的注释源代码历史记录的一些好处？
Let me pose a bit of background information before asking my question:
I recently joined a new software development group that uses Rational tools for configuration management, including a source control and change management system.
In addition to these tools, the team has a standard practice of noting any code changes as a comment in the code, such as:
///<history>
[mt] 3/15/2009 Made abc changes to fix xyz
///</history>
Their official purpose for the commenting standard is that "the comments provide traceability from requirement to code modification".
I am preparing to pose an argument that this practice is unnecessary and redundant; that the team should get rid of this standard immediately.
To wit - the change management system is the place to build traceability from requirement to code modification, and source control can provide detailed history of changes by performing a Diff between versions. When source code is checked in, the corresponding change management ticket is noted. When a CM ticket is resolved, we note which source code files were modified. I believe this provides a sufficient cross-reference for the desired traceability.
I would like to know if anyone disagrees with my argument. Am I missing some benefit of commented source code history that change management and source control systems cannot provide?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（6）
就我自己而言，我总是发现此类注释比它们的价值更麻烦：它们可能会导致合并冲突，当您尝试隔离两个版本之间的差异时可能会显示为“误报”，并且可能会引用代码更改此后已被后来的更改所废弃。
通常（并非总是，但经常）可以更改版本控制系统而不丢失元数据。 如果您要将代码移动到不支持此功能的系统，那么在切换之前编写一个脚本将更改历史记录转换为注释并不困难。
For myself, I have always found such comments to be more trouble than they're worth: they can cause merge conflicts, can appear as 'false positives' when you're trying to isolate the diffs between two versions, and may reference code changes that have since been obsoleted by later changes.
It's often (not always, but often) possible to change version-control systems without losing metadata. If you were to move your code to a system that doesn't support this, it would not be hard to write a script to convert the change history into comments before the cutover.
注释允许您在代码中相关的位置找到所有更改及其原因，而无需深入研究差异和版本控制系统的复杂性。 此外，如果您决定更改版本控制系统，评论将保留。
我从事过一个具有类似实践的大型项目，该项目已经更改了两次源代码控制系统。 没有一天我不高兴收到这些评论。
是多余的吗？ 是的。
有没有必要？ 不。
A comment allows you to find all the changes and their reasons in the code right where they are relevant without having to dig into diffs and version control system intricacies. Furthermore, should you decide to change of version control system, the comments will stay.
I worked on a large project with similar practice that had changed of source control system twice. There wasn't a day when I wasn't glad to have these comments.
Is it redundant? Yes.
Is it unnecessary? No.
我一直认为代码当然应该受到版本控制，并且当前源代码（您今天可以打开和阅读的源代码）应该仅在当前有效紧张。
如果报表过去最多可以有 3 个轴，那么上个月您将其更新为支持最多 6 个轴，这并不重要。 无论你扩展了一些功能还是修复了一些bug，只要当前版本能够容易理解就可以了。 当你修复一个bug时，只需留下固定的代码即可。
不过，有一个例外。 如果（且仅当）固定代码对您来说看起来不如之前的错误代码直观； 如果您觉得明天有人可能会来，并且只是通过阅读代码，就想将其改回“看起来更正确”，那么最好添加一条注释：“This is did this避免的方法......等等等等。”此外，如果背后的问题是团队文化中臭名昭著的战争故事，或者由于某种原因错误报告数据库包含有关这部分代码的非常有趣的信息，我认为在解释性评论中添加“（参见 Bug Id 10005）” 并没有什么不正确的。
I've always thought that code should be, of course, under version control, and that the current source code (the one that you can open and read today) should be valid only in present tense.
It doesn't matter if a report could have up to 3 axis in the past and last month you updated it to support up to 6 axis. It doesn't matter if you expanded some function or fixed some bug, as long as the current version can be easily understood. When you fix a bug, just leave the fixed code.
There's an exception, though. If (and only if) the fixed code looks less intuitive to you than the previous, incorrect one; if you feel that someone might come tomorrow and, just by reading the code, be tempted to change it back to what "seems more correct", then it's good to add a comment: "This is done this way to avoid... blah blah blah." Also, if the problem behind is an infamous war story inside the team's culture, or if for some reason the bug report database contains very interesting information about this part of the code, I wouldn't find it incorrect to add "(see Bug Id 10005)" to the explaining comment.
我首先想到的是供应商锁定。 如果您曾经离开过 Rational，那么您需要确保在迁移期间维护了完整的更改历史记录——而不仅仅是工件的版本。
The one that jumps to mind to me is vendor lockin. If you ever moved away from Rational, you'd need to make sure that the full change history was maintained during the migration - not just the version of the artifacts.
当您在代码中时，您需要知道为什么它是这样的结构，因此在代码注释中。 位于代码之外的工具尽管可能很好，但需要大脑进行太多的上下文转换才能发挥作用。 除此之外，尝试从文档和差异中对代码意图进行逆向工程非常困难，我宁愿每天阅读一行注释。
When you're in the code you need to know why it's structured like that, hence in code commenting. Tools that sit outside the code, good though they may be, require far too much of a context shift in your brain to be useful. As well as that, trying to reverse engineer the code intent from documentation and a diff is pretty damn hard, I'd much rather read a line of comment any day.
在我工作的代码中有一个阶段，早在 1994-96 年的时间范围内，就有在文件顶部插入更改历史注释的趋势。 这些注释现在毫无意义且无用，我在编辑包含此类注释的文件时执行的许多标准清理之一就是删除它们。
相比之下，在进行更改的位置也有一些带有错误编号的注释，通常解释了为什么荒谬的代码是这样的。 这些可能非常有帮助。 错误编号让您可以在其他地方查找信息，并找出罪魁祸首（或受害者 - 情况各不相同）。
另一方面，像这样的物品 - 正品； 上周清理干净了——让我咬紧牙关。
NT 团队的判断是正确的； 我不明白为什么他们认为这是一个特定于平台的修复。 当然，如果代码之前使用原型而不仅仅是无参数声明，那么 Unix 团队也必须修复代码。 该评论是有帮助的 - 向我保证该错误是真实的 - 但令人恼火。
There was a phase in the code I work on, back in the 1994-96 time frame, where there was a tendency to insert change history comments at the top of the file. Those comments are now meaningless and useless, and one of the many standard cleanups I perform when editing files containing such comments is to remove them.
In contrast, there are also some comments with a bug number at the location where the change is made, typically explaining why the ridiculous code is as it is. These can be very helpful. The bug number gives you somewhere else to look for information, and fingers the culprit (or victim - it varies).
On the other hand, items like this one - genuine; cleaned up last week - make me grit my teeth.
The NT team got the call correct; why they thought it was a platform-specific fix is beyond me. Of course, if the code had used prototypes instead of just parameterless declarations before now, then the Unix team would have had to fix the code too. The comment was a help - assuring me that the bug was genuine - but exasperating.