Question

为什么要添加

// Bug 1024

对源代码控制代码库的评论？大多数错误跟踪和源代码控制系统都可以更好地跟踪这些信息。在源代码管理中，标签或注释可与签入一起使用。在错误跟踪器中，可以将修订号添加到错误的解决方案中。为什么要评论代码呢？特别是因为这些评论的相关性非常短暂，并且它们倾向于乱扔垃圾代码库。

Answer 1

我发现其中一个在我们的代码库中有用。

我说“为什么他第二次调用初始化函数，这在工作流程的后期？”

错误评论让我对问题描述说得对。当我重新编写代码时，我肯定会在我的测试中包含该错误，并且没有重新引入它。

虽然我会说，总的来说，我同意你的意见，不要自己插入。

我希望有问题的开发人员能够以更有意义的方式修复错误，这样我就不用担心代码了。

Answer 2

最终，我认为这是一个不好的做法。最好包括错误存在的原因（Y型的foos没有属性Z）。如果您愿意，可以在“BugId 12345”中添加“更多内容”。

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

Answer 3

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

然后你可以去看看1024，看看在做出新修复之前的原因，原因和时间 - “一个统治它们的人”。

如果错误号不在提交消息中，则必须搜索提交修复的错误 - 可能是几个（如果错误报告多次）。

Answer 4

你永远不应该只添加错误号。如果你为一个bug做了多次签到，你应该添加错误号和主题，以及任何限定符：

Bug 1111 - Foo在64位系统上被破坏。修复＃2，因为它在合并到主干后重新打开。

某些系统具有错误号集成。在mxr.mozilla.org中，cvs日志显示中的错误号自动神奇地转换为bugzilla.mozilla.org号码的链接。当你在挖掘代码时，这是一个巨大的节省时间。我认为Fogbugz有类似的功能......

此外，即使您的系统没有，它通常也会有所帮助，因为没有人希望在评论中看到更改的整个上下文，这就是错误跟踪器的用途。

Answer 5

纯粹的懒惰。当然，从长远来看需要更多的时间，但在短期内“// Bug 1024”不会付出任何努力。你拥有的代码越多，这就越糟糕。

Answer 6

我认为这是“我有锤子，必须钉子”的情况。您的文本编辑器或IDE不是管理代码的唯一工具。

历史记录最好在代码外部维护。代码的含义应该在注释中描述，而不是立即显而易见。

我同意错误号应该在源代码控制提交消息中。

Answer 7

我不这样做。我想不出你为什么要把缺陷ID放在代码中的一个很好的理由。我会把它放在发行说明/更改日志上。

我觉得有用的是在自动测试中使用缺陷ID作为名称的一部分：

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

我见过other projects做同样的事情。

Answer 8

我很惊讶有多少人反对这一点。我个人对此的感觉是，这些是非常好的想法。我同意之前的评论，它应该包含的不仅仅是错误号，最好还包括一个简短的摘要，并在适当时链接到错误跟踪系统。

这些评论的好处只在具有历史记录和大量先前错误修复的旧项目中显而易见。您不必在任何地方进行这些注释，但是如果放在可能没有上下文的情况下没有意义的代码块之前，它们非常有用。在任何类型的相当复杂的系统中，都会有代码片段在没有上下文的情况下看似不合逻辑或不必要。

由于与系统或旧解决方法的交互，代码是是必要的。为了防止某人稍后重新引入修补的bug，表示代码块旨在修复的错误非常有用，最好附加一些类型的解释。否则，您依赖于某人在提交日志中记录的原因仔细检查提交历史记录，这是非常不可能的，特别是如果有人重构代码。

编辑：我指的是将这些代码块放到一个不寻常或需要额外上下文的代码块中。评论你所做的每一个错字修正都没有帮助或必要： - ）

Answer 9

我发现它在解释本来看似错误的代码时非常有用，并且也可用于提交消息。

Answer 10

我同意你的观点，这样的评论并不是真的有用而且太简短了。

然而，通过引用缺陷跟踪系统中的记录（或者扩展到您可能拥有的任何KM存储库）来评论代码是非常有用和重要的。

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

因此，将代码标记为属于特定错误修复程序会使其在重新分解期间可见，从而提示开发人员在更改代码之前查看错误描述。它还有助于重新打开错误的情况 - 如果您必须多次更改代码的相同部分，您可能会考虑在替代解决方案中投入时间。

P.S。您可以从Joel On Software考虑this关于MS Office的文章。据我所知，MS Office和MS Windows的代码中充满了类似的评论，这些评论解释了开发人员早已做出的决定。

Answer 11

如果您正在浏览不熟悉的源代码，并且看到一些不明显的内容，那么很高兴知道原因。这是一个判断调用，并非每个错误修复都需要这样的解释 - 如果没有它，大多数错误可能会消失。

Answer 12

如果有足够的理由相信某人在查看部分代码时想知道错误号，那么添加一个提及错误的评论可能会非常好（希望它也会解释错误的重要部分，不过）。

是的，源代码控制提交消息还应该包含错误号，并查看修订日志可以为您提供相同的信息......但是如果代码的相同部分被多次更改，但是从中获取的详细信息最初的错误仍然适用，可能需要一段时间才能找到原始更改以了解该错误。

此外，当有充分的理由将代码从一个类移动到另一个类或重命名文件时会出现这种情况，这会使找到某个代码段背后原因的根本更加困难（重命名不是这样） SVN的问题很多，但CVS却很痛苦。

Answer 13

你的头上钉满了“相关性非常短暂，他们倾向于乱扔垃圾代码库。”

在源文件中构建的每一点无用的东西都会使它们的可读性降低，难以维护。删除所有不增值的内容。 “Bug 12345”现在没什么价值，几周之内就没有了。

Answer 14

我们正在开发一个包含许多开发人员和多个已发布分支的大型系统。

这些错误引用注释在从一个分支移植到另一个分支时实际上非常有用，特别是因为我们使用的SCM系统功能很差，并且提交注释很难获得或者可能很老。

如果修复很简单，那么可能不需要bug标记。如果它不明显，那么引用Bug然后在评论部分写一个长解释可能更有意义。

Answer 15

我做了这个，直到Visual Studio 2008附带注释。在回顾旧代码时，它很有用，可以立即看到至少在特定代码决策背后的想法。

是的，我知道你可以与以前的版本进行比较，但是当你只是需要对次要代码更新感觉良好时，这就是一种痛苦。

Answer 16

我不喜欢这种涂鸦。就像其他令人厌恶的生命形式一样，它们会随着时间的推移而累积，扼杀代码库。

当人们修复与先前错误修复重叠的错误时，问题才真正开始。然后，您将错误号标记为一段错误或误导性的代码。

Answer 17

这种评论 IS 非常有用：当您更改错误跟踪或源代码控制工具时会发生什么？对BZ1722和FB3101的引用会告诉您要检查的跟踪工具（例如Bugzilla或FogBugz）。

Answer 18

这是件好事！

正在查看代码的人不太可能欣赏代码的完整历史记录，并且很可能撤消一个非常重要的更改，因为他们之前可能没有在代码的这个区域中工作过。它可以解释看起来疯狂的代码或客户要求等同于奇怪的代码。

您不能总是通过架构和代码捕获客户需求的细节，特别是当他们要求愚蠢的东西时。因此，当你被迫这样做时，你从敏感开始，然后将代码精炼或破解成愚蠢的，bug编号支持疯狂代码的意图。

错误编号评论

18 个答案: