你为什么要添加

//Bug 1024

注释到源代码控制的代码库中？
大多数错误跟踪和源代码控制系统都配备得更好，可以跟踪此信息。
在源代码管理中，标签或者注释可以与签入一起使用。在错误跟踪器中，可以将修订号添加到错误的解决方案中。那么，为什么要注释代码？特别是因为这些注释的相关性很短，并且往往会堆积乱码。

解决方案

纯粹的懒惰。当然，从长远来看，这会花费更多的时间，但是从短期来看，" // Bug 1024"不会花费任何精力。我们拥有的代码越多，情况就越糟。

最终，我认为这是一个不好的做法。最好包括为什么存在该错误(Y类型的foo没有属性Z)。我们可以根据需要添加" BugId 12345中的更多内容"。

如果我们要进行多个级别的集成，则trac中的源代码视图可以直接链接到BugId。

我一直这样做，直到Visual Studio 2008附带注释。当回顾旧代码时，立即发现至少在某个特定代码决策背后有想法，这很有用。

是的，我知道我们可以将它与以前的版本进行比较，但是当我们只需要快速了解次要代码更新时，这就是一个麻烦。

假设我们有一个新的错误，可以追溯到修订版12345中的更改。查看日志，它立即告诉我们错误1024是进行更改的原因。

然后，我们可以查看1024，以了解在进行新修复之前，"为什么要全部解决"的原因，原因和时间。

如果该错误号不在提交消息中，则必须搜索一个已修复的错误，该错误可能是多个(如果多次报告该错误)。

前几天，我在我们的代码库中发现了其中一项有用的功能。

我说："为什么他要在工作流程中这么晚才第二次调用初始化函数？"

错误注释使我可以正确地描述问题。当我重新编写代码时，我确定要在测试中包含该错误，并且不会重新引入它。

尽管我会说总体上我同意意见，但不要自己插入这些内容。

我本来希望有问题的开发人员以更有意义的方式修复该错误，这样我一开始就不必担心代码。

我同意你的看法，这样的评论并没有真正的帮助，而且太简短了。

但是，注释代码以引用缺陷跟踪系统中的记录(或者扩展到我们可能拥有的任何KM信息库)都是非常有用且重要的。

有时会更改代码以对应用程序行为的某个问题实施解决方法。有时，引入的解决方法绝不是合乎逻辑的。经常发生的情况是，当其他人更新代码时，作为重构工作的一部分，这些"不好"的代码会被删除。

因此，将代码标记为属于特定的错误修复程序使其在重构期间可见，从而促使开发人员在更改代码之前查看错误说明。如果必须多次更改同一部分代码，我们可能会考虑在替代解决方案上花费时间，那么在重新打开该错误的情况下，它也很有帮助。

P.S.我们可能认为Joel On Software的有关MS Office的这篇文章会有所帮助。据我所知，MS Office和MS Windows的代码充满了类似的注释，这些注释解释了由开发人员做出的决策早已不复存在。

在解释否则可能看起来是错误的代码以及用于提交消息时，我发现它很有用。

如果我们正在浏览不熟悉的源代码，并且发现了一些不明显的地方，那么很高兴知道原因。但是，这是一个判断电话，并不是每个错误修复都需要这样的解释，如果没有它，大多数人可能会逃脱。

我认为这是"我有锤子，一定是钉子"的情况。文本编辑器或者IDE并不是管理代码的唯一工具。

最好在代码外部维护历史记录。当代码的含义不是很明显时，应在注释中加以说明。

我同意错误编号应该在源代码管理提交消息中。

我不那样做我想不出为什么要将缺陷ID放入代码中的充分理由。我将其放在发行说明/变更日志中。

我发现有用的是将缺陷ID用作自动化测试中名称的一部分：

[TestFixture]
public class Release_1_2_Bugfixes
{
  [Test]
  public void TestBug42()
  {
    Assert.AreEqual(42, CalculateAnswerToLifeUniverseAndEverything());
  }
}

我看过其他项目也做同样的事情。

如果有足够的理由相信某人在查看部分代码时想知道错误号，那么添加提及该错误的注释可能会很好(希望它也可以解释该错误的重要部分)。

是的，源代码管理提交消息中还应该包含错误号，并且浏览修订日志可以为我们提供相同的信息...但是，如果代码的同一部分被多次更改，但是从最初的错误中学到的细节仍然存在适用于此，可能需要一段时间才能找到原始更改，以了解该错误。

同样，当出现将代码从一个类移到另一类或者重命名文件的充分理由时，也会出现这种情况，这将使得更难于找到某个代码部分背后的原因根源(将代码重命名得很少) SVN的问题，但CVS的痛苦)。

我们绝不应该只添加错误号。如果我们对一个错误进行了多次签入，则应添加错误号和主题，以及所有限定符：

错误1111 Foo在64位系统上失败。修复＃2，因为在合并到主干后重新打开了它。

某些系统具有错误号集成。在mxr.mozilla.org中，cvs日志显示中的错误号会自动变为指向bugzilla.mozilla.org编号的链接。当我们在研究代码时，这是一个巨大的节省时间。我认为Fogbugz具有类似的功能...

同样，即使系统没有这样做，它也通常会有所帮助，因为没有人希望看到注释更改的整个上下文，这就是Bug跟踪器的作用。

头上钉着"相关性很短，它们往往会堆积乱码。"

源文件中堆积的每一个无用的东西都使它们的可读性和维护性有所降低。删除所有不会增加价值的内容。 " Bug 12345"现在几乎没有价值，并且在几周内将没有任何价值。

我们在具有许多开发人员和多个已发布分支的大型系统上工作。

这些错误参考注释实际上在从一个分支移植到另一个分支的过程中非常有用，尤其是因为我们使用的SCM系统的功能非常差，并且提交注释很难获得甚至可能很旧。

如果修复很简单，则可能不需要错误标记。如果不是很明显，则先参考Bug，然后在注释部分写一个长说明可能更有意义。

我不喜欢这种涂鸦。像其他令人讨厌的生命形式一样，它们随着时间的推移而积聚，使代码库窒息。

当人们进行的错误修复与以前的错误修复重叠时，问题就真正开始了。然后，我们将有bug号标记为一段代码，这根本是错误的或者误导性的。

令我惊讶的是，有多少人反对这一点。我个人对此的看法是，这是一个非常好的主意。我同意较早的评论，即它不仅应包括错误号，而且最好包括简短的摘要，并在适当的情况下链接到错误跟踪系统。

仅在具有历史记录和大量以前的错误修复的较旧项目中，这些注释的好处才显而易见。我们不必在所有地方都做这些注释，但是当放置在没有上下文可能没有意义的代码块之前时，它们将非常有帮助。在任何类型的相当复杂的系统中，如果没有上下文，就会出现一些看起来不合逻辑或者不必要的代码片段。

由于与系统的交互作用或者旧的解决方法，因此需要代码。为了防止以后有人重新引入已修补的错误，最好将代码块设计为要修复的错误表示出来，最好附上某种说明。否则，我们将依赖某人，因为提交日志中记录的原因而仔细检查提交历史，这种情况极不可能发生，尤其是在有人重构代码时。

编辑：我指的是将它们与不寻常的代码块或者需要添加上下文的代码块放在一起。评论我们所做的每个拼写错误都是无济于事的或者没有必要的:-)

这种注释非常有帮助：更改错误跟踪或者源代码控制工具时会发生什么？参考BZ1722与FB3101可以告诉我们要检查哪种跟踪工具(例如，Bugzilla或者FogBugz)。

那是一件好事！

查看代码的人不太可能欣赏代码的完整历史，并且可能会撤消非常重要的更改，因为他们以前可能没有在代码的这一领域工作过。它可以解释看起来很疯狂的代码或者等效的客户需求。

我们无法始终通过体系结构和代码来捕获客户需求的详细信息，尤其是当客户要求愚蠢的东西时。因此，我们从明智的角度开始，然后在我们被迫这样做时将代码提炼或者修改为愚蠢的代码，错误号支持了疯狂代码的意图。