我的一些同事在其错误修复中使用特殊注释，例如：

// 2008-09-23 John Doe - bug 12345
// <short description>

这有意义吗？
我们是否以特殊方式评论错误修复？

请告诉我。

解决方案

仅当解决方案特别聪明或者难以理解时。

像这样的注释就是为什么Subversion允许我们在每次提交时都键入一个日志条目的原因。那是我们应该在其中放置这些内容的地方，而不是在代码中。

我不会发表这样的评论，源代码控制系统已经保留了该历史记录，并且我已经能够记录文件的历史记录。

我确实发表了评论，描述了为什么要做一些不明显的事情。因此，如果错误修复使代码的可预测性和清晰度降低，那么我将解释原因。

随着时间的流逝，它们会积累并增加混乱。最好弄清楚代码，为可能不明显的相关陷阱添加任何注释，并将错误详细信息保留在跟踪系统和存储库中。

虽然我的确会在工作中看到一些关于代码错误的评论，但我个人的偏爱是将代码提交链接到一个错误。当我说一个我真的是一个错误。之后，我们始终可以查看所做的更改，并知道将这些错误应用于哪些错误。

为了找到特定的评论，我们使用DKBUGBUG，这意味着David Kelley的修复程序和审阅者可以轻松地标识，当然，我们将在此添加Date和其他VSTS错误跟踪编号等。

我倾向于不在实际来源中发表评论，因为可能很难保持最新状态。
但是，我确实将链接注释放在源代码控制日志和问题跟踪器中。例如我可能会在Perforce中执行以下操作：

[Bug-Id] Problem with xyz dialog.
  Moved sizing code to abc and now
  initialise later.

然后，在我的问题跟踪器中，我将执行以下操作：

Fixed in changelist 1234.
  
  Moved sizing code to abc and now
  initialise later.

因为这样就留下了一个很好的历史标记。如果我们想知道为什么特定的代码行是某种特定的方式，那么它也很容易，我们可以查看文件历史记录。找到代码行后，我们可以阅读我的提交注释，并清楚地看到它是针对哪个错误以及如何对其进行修复的。

我通常会添加自己的姓名，电子邮件地址和日期以及对更改内容的简短描述，这是因为作为顾问，我经常会修改他人的代码。

// Glenn F. Henriksen (<[email protected]) - 2008-09-23
// <Short description>

这样，代码所有者或者跟在我后面的人就可以弄清楚发生了什么，并且如果需要的话可以与我联系。

(是的，不幸的是，他们经常没有源代码控制...对于我使用TFS跟踪的内部内容)

不，我不喜欢，而且我讨厌像乱扔垃圾一样乱涂乱码。错误编号可以在提交到版本控制系统的提交消息中进行跟踪，也可以通过脚本将相关的提交消息推送到错误跟踪系统中进行跟踪。我不认为它们属于源代码，将来的编辑只会使事情变得混乱。

尽管这在当时似乎是个好主意，但很快就变得一发不可收拾。使用源代码控制系统和错误跟踪器的良好组合，可以更好地捕获此类信息。当然，如果发生了一些棘手的问题，则在任何情况下，描述情况的注释都将有所帮助，但日期，名称或者错误编号无济于事。

我目前在工作的代码库已有20多年的历史了，他们似乎在几年前就添加了很多注释。幸运的是，他们在90年代后期将所有内容转换为CVS后几年就停止了这样做。但是，这样的注释在整个代码中仍然是乱七八糟的，现在的政策是"如果直接在该代码上工作，请删除它们，否则请保留它们"。通常很难遵循它们，特别是如果多次添加和删除相同的代码(是的，它发生)。它们也不包含日期，但是包含必须在旧系统中查找才能找到日期的错误号，因此没有人找到。

不要复制VCS将保留给元数据。日期和名称应在VCS自动添加的位置。票证编号，请求更改的管理员/用户名等应在VCS注释中，而不是代码中。

而不是这样：

// $ DATE $ NAME $ TICKET
//对下一个可怜的灵魂有用的评论

我会这样做：

//对下一个可怜的灵魂有用的评论

如果该错误修复程序涉及的内容不是很简单，我会这样做，但是如果该错误修复程序需要详细说明，那么我会经常这样做，这是因为它表示该修复程序的设计欠佳。有时，我必须解决无法更改的公共界面，因此这往往是这些注释的来源，例如：

// <date> [my name] - Bug xxxxx happens when the foo parameter is null, but
// some customers want the behavior.  Jump through some hoops to find a default value.

在其他情况下，源控件提交消息就是我用来注释更改的内容。

通常，这样的注释会更加令人困惑，因为我们实际上对原始代码的外观或者原始不良行为没有真正的了解。

通常，如果错误修复现在使代码正确运行，则只需不加注释即可。无需注释正确的代码。

有时，错误修复使事情看起来很奇怪，或者错误修复正在测试与众不同的东西。然后，通常有一条注释，通常该注释应回溯到错误数据库中的"错误编号"。例如，我们可能有一个注释，其中指出"错误123表示用户在640 x 480屏幕分辨率下的行为异常"。

这种注释风格在多开发人员环境中非常有价值，因为在这种环境中，整个开发人员(例如，到处都是)拥有各种技能和/或者业务知识。

对于经验丰富，知识渊博的开发人员，更改的原因可能很明显，但对于较新的开发人员，此评论将使他们三思而后行，然后再进行深入研究。它还可以帮助他们了解有关系统工作原理的更多信息。

哦，还有关于"我刚刚将其放入源代码控制系统"的经验注释：

如果不在源中，则不会发生。

由于无法使用源代码控制软件，不正确的分支模型等原因，我无法统计丢失项目源历史记录的次数。
更改历史记录不会丢失，只有一个地方在源文件中。

我通常先把它放在那里，然后在签入时剪切'n粘贴相同的注释。

如果在维护代码几年后像这样添加注释，我们将有很多错误修复注释，我们将无法阅读代码。

但是，如果我们将看起来正确(但有细微错误)的内容更改为更复杂的内容，则可以添加简短的注释来解释我们所做的事情，这样一来，下一个维护此代码的程序员就不会将其改回， (或者她)认为我们没有充分的理由使事情变得过于复杂。

如果代码是在实时平台上，而不是直接访问源代码控制存储库，那么我将添加注释以突出显示所做的更改，作为对实时系统上的错误进行修复的一部分。

否则，我们在签到时输入的任何消息都不应包含我们需要的所有信息。

干杯，

抢

否。我使用Subversion并始终输入我进行更改的动机的描述。我通常不使用英语重述解决方案，而是总结所做的更改。

我从事过许多项目，在进行错误修复时，他们在代码中添加了注释。有趣的是，可能不是偶然的，这些项目或者不使用任何类型的源代码控制工具，或者被管理层要求遵循这种惯例。

老实说，在大多数情况下，我并没有真正看到这样做的价值。如果我想知道更改了什么，我将看一下Subversion日志和diff。

只是我的两分钱。

当我在第三方库/组件中进行错误修正/增强时，我经常会发表一些评论。如果我需要使用库/组件的较新版本，这将使查找和移动更改更加容易。

在我自己的代码中，我很少评论错误修正。

我不在多人项目中工作，但有时会在单元测试中添加有关某个错误的注释。

请记住，没有错误，只有不足的测试。

由于我会尽可能地进行TDD(其他一切都是社会自杀，因为其他所有方法都会迫使我们工作无休止)，因此我很少修复bug。

大多数时候，我会在代码中添加像这样的特殊说明：

// I KNOW this may look strange to you, but I have to use
// this special implementation here - if you don't understand that,
// maybe you are the wrong person for the job.

听起来很刺耳，但是大多数自称为"开发人员"的人都别无他法。