我们商店的资深开发人员坚持认为，每当修改代码时，负责的程序员都应添加内联注释，说明他的所作所为。这些评论通常看起来像// YYYY-MM-DD <User ID> Added this IF block per bug 1234.

我们使用TFS进行版本控制，在我看来，这种注释更适合作为签入注释而不是内联噪音。TFS甚至允许您将签入与一个或多个错误关联。我们一些较旧的，经常修改的类文件看起来好像它们的LOC比率接近1：1。在我看来，这些注释使代码更难阅读并添加零值。

这是其他商店的标准做法（或至少是常见做法）吗？

我通常认为这样的评论是不好的做法，我认为这类信息属于SCM提交日志。在大多数情况下，这只会使代码更难阅读。

但是，我仍然经常对特定类型的编辑执行类似的操作。

案例1-任务

如果您使用诸如Eclipse，Netbeans，Visual Studio之类的IDE（或通过某种方式在代码库上进行文本搜索以及其他操作），也许您的团队会使用某些特定的“注释标签”或“任务标签”。在这种情况下，这可能会很有用。

在查看代码时，我会不时添加以下内容：

// TOREVIEW: [2010-12-09 haylem] marking this for review because blablabla

要么：

// FIXME: [2010-12-09 haylem] marking this for review because blablabla

为此，我使用了在任务视图中可以在Eclipse中看到的不同的自定义任务标签，因为在提交日志中包含某些内容是一件好事，但是当您的主管在审查会议中问您为什么完全忘记了bugfix XY时，这还不够溜走了 因此，在紧急事件或真正可疑的代码段上，这可以作为附加的提醒（但通常我会保留简短的注释并检查提交日志，因为这正是提醒的目的，因此我也不会使代码混乱许多）。

案例2-第三方库的补丁

如果我的产品由于某种原因需要打补丁，因此需要将第三方代码打包为源代码（或库，但从源代码重新构建），那么我们会将补丁文件记录在单独的文档中，在其中列出这些“漏洞”供将来参考，并且源代码通常包含类似于以下内容的注释：

// [PATCH_START:product_name]
//  ... real code here ...
// [PATCH_END:product_name]

情况3-非显而易见的修复

这个问题更具争议性，与您的高级开发人员所要求的更接近。

在我目前正在研究的产品中，有时（绝对不是一件平常的事情）会有这样的评论：

// BUGFIX: [2010-12-09 haylem] fix for BUG_ID-XYZ

我们仅在错误修正不明显且代码读取异常的情况下执行此操作。例如，对于浏览器怪癖就是这种情况，或者仅由于产品中存在文档错误，才需要实施晦涩的CSS修复。因此，一般而言，我们会将其链接到我们的内部问题存储库，该存储库中将包含错误修正背后的详细原因以及指向外部产品错误文档的指针（例如，针对知名Internet Explorer 6缺陷的安全建议，或者这样的东西。

但是如上所述，它非常罕见。借助task标签，我们可以定期运行这些标签，并检查这些怪异的修补程序是否仍然有意义或可以逐步淘汰（例如，如果我们首先放弃了对引起问题的bug产品的支持）。

就是这样：一个真实的例子

在某些情况下，总比没有好:)

我刚刚在我的代码库中遇到了一个巨大的统计计算类，其中的标头注释以带有常规yadda yadda的变更日志的形式出现：审阅者，日期，错误ID。

最初，我想到了报废，但我发现错误ID不仅与我们当前问题跟踪器的约定不匹配，而且与我加入公司之前使用的跟踪器之一都不匹配。因此，我尝试通读代码并了解类的工作方式（不是统计学家），还尝试提取这些缺陷报告。碰巧的是，它们非常重要，并且会在不了解文件的情况下使下一个家伙编辑文件，这很可怕，因为它处理原始用户发出的非常具体的要求时，会遇到一些小的精度问题和特殊情况。 。底线是，如果这些东西不在那儿，我就不会知道。如果他们没有去过那里，而我对课堂有更好的了解，

有时很难跟踪这样的非常老的要求。最后，我仍然删除了标头，但是在每个隐含函数之前潜入了一个块注释之后，描述了为什么这些“怪异”的计算是特定的请求。

因此，在那种情况下，我仍然认为这是一种不好的做法，但是男孩很高兴原来的开发人员至少将它们加入了！最好改为清晰地注释代码，但是我想总比没有好。

我们将这种做法用于不受版本控制的文件。我们有在大型机上运行的RPG程序，事实证明，除了备份它们之外，做更多的事情是困难的。

对于版本化的源代码，我们使用签入说明。我认为这就是它们的所在，而不是使代码混乱。毕竟是元数据。

我们以前很久以前就在一家软件商店进行这种练习，我们的经理坚持认为他希望能够读取纸上的代码文件并遵循其修订历史记录。不用说，我不记得他实际查看源文件打印输出的任何具体情况：-/

幸运的是，从那时起，我的经理们对版本控制系统的功能有了更深入的了解（我必须补充说，我们在第一家商店使用过SourceSafe）。因此，我不会在代码中添加版本控制元数据。

如果您的SCM和IDE允许您使用“显示批注”（无论如何在Eclipse中称为“注释”）功能，则可以轻松查看哪些提交更改了一段代码，并且提交注释应说明谁和原因，通常不需要。

我唯一在代码中加上这样的注释的地方是，如果这是一段特别奇怪的代码，可能在将来引起某人的困惑，我将简短地对bug号进行注释，以便他们可以访问bug报告并阅读。详细介绍。

显然，随着时间的推移，几乎所有此类评论都将保证是不正确的；如果您两次编辑一行，是否添加两个注释？他们去哪里？因此，更好的过程是依靠您的工具。

这表明，无论出于何种原因，高级开发人员都不能依靠新流程来跟踪更改并将更改连接到问题跟踪系统。您必须解决这种不适感才能解决冲突。

您需要了解为什么他不能依靠它。这是旧习惯吗？SCM系统的不良体验？演示格式对他不起作用？也许他甚至不了解'git blame'和Perforce的时间轴视图之类的工具（本质上显示了这一点，尽管它可能未显示是什么问题触发了更改）。

如果不了解他提出要求的原因，您将无法说服他。

我使用20多年的Windows产品。我们有类似的做法已经存在很长时间了。我无法计算这种做法节省了培根的次数。

我同意某些东西是多余的。过去，开发人员使用这种做法来注释掉代码。当我查看此内容时，我告诉他们继续删除代码，并且不需要注释。

但是，在很多时候，您会看到已经使用了大约十年并由20个开发人员修改但从未重构过的代码。每个人都早就忘记了原始代码中的所有需求详细信息，不用管所有更改，也没有可靠的文档。

带有缺陷编号的注释使我有地方可以查找代码的来源。

因此，是的，SCM系统可以执行很多操作，但不能完成所有操作。像对待其他任何评论一样对待它们，并在进行重大更改的地方将其添加。开发人员将在5年以上的时间里查看您的代码，我们将非常感谢您。

如果您有VCS，则提及注释中的每个更改都是没有意义的。提及特定错误或与特定行相关的其他重要说明很有用。更改可能包括许多更改的行，所有行都在同一提交消息下。

我不能说。

我会在执行过程中在代码中添加TODO，目的是在检查时删除它们。