错误号注释

前几天,我在代码库中发现其中一个有用。

我说,“为什么他在工作流的后期第二次调用初始化函数?“

错误评论让我正确地理解了问题描述。当我重新编译代码时,我确信在我的测试中包含了这个bug,并且没有重新引入它。

虽然我会说,一般来说,我同意你的意见,并且不插入那些我自己。

我更希望有问题的开发人员以更有意义的方式修复这个bug,这样我就不必首先对代码产生疑问了。

最后,我认为这是一个糟糕的做法。最好包括bug存在的原因(Y类型的foo没有属性Z)。如果您愿意,还可以在bugid 12345中包含一个“more-in-bugid 12345”。

如果您在多个级别上进行集成,那么trac中的源代码视图可以直接链接到bugid。

纯粹的懒惰。当然,从长远来看需要更多的时间,但从短期来看,“//bug 1024”一点都不费吹灰之力。代码越多,情况就越糟糕。

假设您有一个新的bug,可以跟踪到12345版本中的更改。您查看日志,它会立即告诉您,进行更改的原因是bug 1024。

然后,您可以查看1024,了解什么、为什么以及何时才能进行新的修复-“一个规则他们所有人”。

如果错误号不在提交消息中,那么您必须搜索提交修复的错误——可能是多个错误(如果错误被报告多次)。

我认为这是一个“我有一把锤子,那一定是钉子”的例子。文本编辑器或IDE不是管理代码的唯一工具。

历史最好在代码外部维护。当代码的含义不明显时,应在注释中描述。

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

您不应该只添加错误号。如果您对单个bug进行了多次签入,则应添加bug编号和主题以及任何限定符:

bug 1111-foo在64位系统上总线。修复2,因为它在合并到主干之后被重新打开。

有些系统集成了错误号。在mxr.mozilla.org中,cvs日志显示中的bug编号会自动神奇地转换为指向bugzilla.mozilla.org编号的链接。当你在挖掘代码时,这是一个巨大的省时器。我认为FogBugz有一个类似的功能…

此外,即使您的系统没有,它通常也会有所帮助,因为没有人想在注释中看到更改的整个上下文,这就是bug追踪器的作用所在。

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

但是,通过引用缺陷跟踪系统中的记录(或者扩展到您可能拥有的任何知识库)来注释代码是非常有用和重要的。

有时会更改代码以实现针对应用程序行为的特定问题的变通方法。有时,引入的解决方案根本不符合逻辑。通常情况下,当其他人更新代码时,这段“糟糕”的代码会作为重新分解工作的一部分被删除。

因此,将代码标记为属于某个特定的bug修复,使其在重分解过程中可见,从而提示开发人员在更改代码之前查看bug描述。在重新打开bug的情况下,它也很有帮助——如果您必须多次更改代码的同一部分,您可能会考虑在另一个解决方案上投入时间。

另外,你可以考虑 this Joel关于微软办公软件的文章很有帮助。据我所知,MS Office和MS Windows的代码充满了类似的评论,这些评论解释了开发人员早已做出的决定。

我发现它在解释那些似乎是错误的代码时很有用,而且在提交消息中也有用。

我不这么做。我想不出一个好的理由来解释为什么您要将缺陷ID放入代码中。我将把它放在发行说明/变更日志上。

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

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

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

我很惊讶有多少人反对这个。我个人的感觉是这些 好的 想法。我同意之前的一条评论,它应该包含的不仅仅是错误号,如果合适的话,最好包括一个简短的摘要和到错误跟踪系统的链接。

这些评论的好处只在具有历史记录和大量以前错误修复的旧项目中明显。您不必在任何地方都做这些注释,但是如果将它们放在没有上下文的代码块之前,它们将非常有用。在任何一种相当复杂的系统中,都会有一些代码片段在没有上下文的情况下显得不合逻辑或不必要。

由于与系统或旧的解决方案的交互,代码 是 必要的。为了防止以后有人重新引入修补过的bug,将代码块设计用来修复的bug表示出来非常有帮助,最好附上某种解释。否则,您将依赖于某个仔细检查提交历史记录的人,原因记录在提交日志中,这是非常不可能的,尤其是在有人正在重构代码的情况下。

编辑 :我指的是将这些代码与一个不寻常的代码块放在一起,或者需要额外的上下文。对你做的每一个打字错误都进行评论是没有帮助或必要的:(-)

直到Visual Studio 2008附带了注释,我才这样做。当回顾旧代码时,立即发现在特定的代码决策背后至少存在思想是很有用的。

是的,我知道您可以与以前的版本进行比较,但是当您只需要对一些小的代码更新有一个快速的感觉时,这真是一个大麻烦。

如果您浏览不熟悉的源代码,并且看到一些不明显的东西,那么很高兴知道原因。不过,这是一个判断性的要求,并不是所有的错误修复都需要这样的解释——可能大多数修复程序都可以在没有它的情况下逃脱。

如果有足够的理由相信有人在查看部分代码时希望知道bug编号,那么添加一条提到bug的注释就可以了(希望它也能解释bug的重要部分)。

是的,源代码管理提交消息也应该包含错误号,查看修订日志可以提供相同的信息…但是,如果代码的同一部分被多次更改,但从初始bug中获得的详细信息仍然适用,则可能需要一段时间才能找到原始更改来了解该bug。

此外,当有一个很好的理由将代码从一个类移动到另一个类,或者重命名文件时,就会出现这种情况,这会使在某段代码后面找到原因的根源变得更加困难(重命名SVN的问题不多,但会给CVS带来痛苦)。

你用“相关性非常短暂,而且它们往往会在代码库中堆积起来”一针见血。

在源文件中积累的每一点无用的代码都会使它们的可读性降低,并且难以维护。删除所有不增值的内容。”现在bug 12345“的值很小,几周后就没有了。

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

在从一个分支移植到另一个分支的过程中,这些错误引用注释实际上是非常有用的,特别是因为我们使用的SCM系统功能非常差,提交注释很难获取或可能很旧。

如果修复很简单,那么它可能不需要错误标记。如果不明显,那么参考一个bug可能更有意义,然后在注释部分写一个长的解释。

我不喜欢这种涂鸦。像其他令人不快的生命形式一样,它们随着时间的推移而增长,阻塞了代码库。

当人们进行与以前的错误修复重叠的错误修复时,问题就真正开始了。然后,在代码的某个部分添加了错误代码或误导代码的bug号。

这种类型的评论 是 非常有用:当您更改bug跟踪或源代码管理工具时会发生什么?BZ1722和FB3101的引用将告诉您要检查的跟踪工具(例如Bugzilla或FogBugz)。

这是件好事!

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

您不能总是通过体系结构和代码捕获客户需求的微小细节,特别是当他们要求一些愚蠢的东西时。因此,您从明智的开始,然后在被迫这样做的时候精炼或黑客代码到愚蠢的地方,错误号支持了疯狂代码的意图。