8

你为什么要加

//错误 1024

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

4

18 回答 18

8

前几天我在我们的代码库中发现其中一个很有帮助。

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

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

虽然我会说，总的来说，我同意你的观点，并且我自己不会插入这些内容。

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

于 2008-10-02T16:15:50.660 回答
4

最后，我认为这是一个不好的做法。最好包括错误存在的原因（Y 类型的 foo 没有属性 Z）。如果需要，您可以在其中包含“更多错误 ID 12345”。

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

于 2008-10-02T16:14:49.743 回答
3

纯粹的懒惰。当然，从长远来看需要更多时间，但从短期来看，“//Bug 1024”一点也不费力。你拥有的代码越多，情况就越糟糕。

于 2008-10-02T16:14:07.857 回答
3

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

然后，您可以查看 1024 以了解内容、原因和时间，然后再进行新的修复 - 即“统治一切的人”。

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

于 2008-10-02T16:14:53.097 回答
3

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

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

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

于 2008-10-02T16:19:27.533 回答
3

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

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

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

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

于 2008-10-02T16:30:32.013 回答
2

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

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

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

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

PS，您可能会认为Joel On Software 的这篇关于 MS Office 的文章很有帮助。据我所知，MS Office 和 MS Windows 的代码中充满了类似的注释，这些注释解释了开发人员早已不复存在的决定。

于 2008-10-02T16:16:58.863 回答
2

我发现它在解释看起来错误的代码时很有用，也适用于提交消息。

于 2008-10-02T16:18:08.970 回答
2

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

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

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

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

于 2008-10-02T16:28:27.010 回答
2

我很惊讶有多少人反对这一点。我个人对此的感觉是，这是一个非常好的主意。我同意之前的评论，即它应该包括的不仅仅是错误编号，如果合适的话，最好包括一个简短的摘要和到错误跟踪系统的链接。

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

由于与系统的交互或旧的解决方法，代码是必要的。为了防止以后有人重新引入已修补的错误，表示代码块旨在修复的错误非常有帮助，最好附上某种类型的解释。否则，由于提交日志中记录的原因，您依赖于某人仔细检查提交历史记录，这是极不可能的，尤其是在有人正在重构代码的情况下。

编辑：我特别指的是把这些放在一段不寻常或需要额外上下文的代码中。评论您所做的每一个错字修复都没有帮助或没有必要:-)

于 2008-10-02T17:52:29.663 回答
1

我一直这样做，直到 Visual Studio 2008 附带注释。当回顾旧代码时，它很有用，可以立即看到至少在特定代码决策背后是经过深思熟虑的。

是的，我知道您可以与以前的版本进行比较，但是当您只需要对较小的代码更新有一个快速的感觉时，这真是让人头疼。

于 2008-10-02T16:14:52.643 回答
1

如果您正在浏览不熟悉的源代码，并且看到一些不明显的东西，那么很高兴知道原因。虽然这是一个判断电话，但并非每个错误修复都需要这样的解释 - 可能大多数人都可以在没有它的情况下逃脱。

于 2008-10-02T16:18:14.383 回答
1

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

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

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

于 2008-10-02T16:30:08.910 回答
1

“相关性非常短暂，它们往往会堆积乱七八糟的代码库”。

源文件中积累的每一点无用的垃圾都会使它们的可读性降低，并且难以维护。删除所有不增加价值的东西。“Bug 12345”现在几乎没有价值，几周后就没有了。

于 2008-10-02T16:45:33.087 回答
1

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

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

如果修复很简单，那么它可能不需要错误标记。如果它不是显而易见的，那么参考一个 Bug 然后在评论部分写一个长的解释可能更有意义。

于 2008-10-02T17:10:37.363 回答
0

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

当人们进行与先前的错误修复重叠的错误修复时，麻烦就真正开始了。然后，您将有错误编号标记一段完全错误或具有误导性的代码。

于 2008-10-02T17:22:04.417 回答
0

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

于 2008-10-02T19:19:00.440 回答
0

那是一件好事！

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

你不能总是通过架构和代码来捕捉客户需求的细节，尤其是当他们要求一些愚蠢的东西时。因此，您从明智的开始，然后当您被迫这样做时，将代码改进或修改为愚蠢的代码，错误编号支持了疯狂代码的意图。

于 2008-10-02T19:55:19.900 回答