Question

如果是这样，你在哪里划线？我的同事和我在这个问题上不同意。我见过这样的事情

// fixes bug # 22

到

// fixed bug: shouldnt be decrementing
i++;

如果更改非常重要，是否可以，并从根本上改变编写方法的内容？或者您只是更改方法的摘要文本以反映它现在要做的事情？

我的意见是这些信息应该放到源代码管理中。有些人说这是坏的，因为它会在源代码控制的上下文之外丢失（比如你切换系统并希望保留历史数据）。

Answer 1

评论应解释这些方法的工作原理。

源代码管理解释了为何进行了更改。

Answer 2

如果你写的是正确的话，添加关于修复错误的评论是一个好主意。

例如，

/* I know this looks wrong, but originally foo was being decremented here, and 
   it caused the baz to sproing. Remember, the logic is negated by blort! */

像Fixes bug #22 这样的东西更好地保存在源代码管理中。您的代码中的注释应该是路标，以帮助未来的旅居者，而不是满足流程和跟踪。

Answer 3

没有。您应该保留有关错误和更改集的信息，以修复源代码外部的错误。代码本身中的任何注释都只与代码所做的事情有关。其他任何东西都只是混乱。

Answer 4

我个人觉得评论应该是代码本身，而不是错误修复。

我的理由是可维护性 - 2年（或10年）后，此评论将不再有意义。在上面的示例中，我更喜欢以下内容：

// Increment i to counteract extra decrement
++i;

不同之处在于它与错误无关，而在于代码正在做什么。评论应该是对代码的评论，而不是元信息，IMO。

这种观点部分是因为我维护了一个非常古老的代码库 - 我们有很多评论不再与错误修复或功能增强请求有关......等等。

Answer 5

我们有一些这样的评论，但随后我们的Bugzilla服务器死了，我们重启错误＃1，所以它们都没有意义。我现在首选的方法是对错误的简短解释。

Answer 6

像// fixes bug # 22之类的东西它本身毫无意义，需要补充步骤才能了解它的含义以及它所发挥的作用。不管您可能使用的错误跟踪或源代码管理软件，我认为简短的描述更合适。

Answer 7

如果算法需要以某种方式编码 - 例如，为了解决第三方API中的错误，那么应该在代码中对其进行评论，以便下一个出现的人不会尝试“优化” “代码（或其他）并重新引入问题。

如果这涉及在修复原始错误时添加注释，请执行此操作。

它还可以作为标记，以便您可以找到检查是否升级到下一版API的代码。

Answer 8

假设评论不是多余的（想到经典的i++; //increment i示例），几乎从来没有理由反对反对添加评论，无论它与什么相关。信息很有用。然而，最好是描述性和简洁 - 不要说“修复bug #YY”，而是添加类似“这曾经失败的x = 0，这里的额外逻辑阻止了”。这样，稍后查看代码的人可以理解为什么特定部分对正常功能至关重要。

Answer 9

我依赖于svn中的FogBugz和签到注释。效果很好，但正如jeffamaphone所说，如果丢失了你的bug数据库，那么案例编号就没有多大意义。

在代码中添加注释的一个问题是，随着时间的推移，您的代码将会被关于一段时间内不存在的问题的评论所困扰。通过在源代码管理签入注释中放置此类注释，您可以有效地将修复程序的信息绑定到更正它的特定版本，这在以后会有所帮助。

Answer 10

我的观点是，评论应与开发人员的意图相关，或围绕算法/方法的“为什么”重点。

评论不应包含固定时间。

Answer 11

我同意此类数据应放在源代码管理或其他部分配置管理中。在代码库中工作，在评论中放置有关错误修复的信息，我可以说它会导致后面的杂乱的评论和代码。修复工作六个月后，您是否真的想知道修复一些长期过去的错误？当您需要重构代码时，如何处理注释？

Answer 12

我们在我的公司使用Team Foundation Server进行源代码控制，它允许您将签入命令与错误报告联系起来，因此我不会直接在代码中添加注释以达到同样的目的。

但是，在我实现代码作为.NET框架或第三方库中的错误的解决方法的情况下，我想将URL放到Microsoft TechNet日志或描述错误及其状态的网站。

Answer 13

很明显

    // fix bug #22
    i++;

不是有效的沟通。

良好的沟通主要是常识。说出你的意思。

    // Compensate for removeFrob() decrementing i.
    i++;

如果有可能帮助未来的读者，请附上错误编号。

    // Skipping the next flange is necessary to maintain the loop
    // invariant if the lookup fails (bug #22).
    i++;

有时重要的对话会记录在您的错误跟踪系统中。有时，错误会导致关键的洞察力改变代码的形状。

    // Treat this as a bleet. Misnomed grotzjammers and particle
    // bleets are actually both special cases of the same
    // situation; see Anna's analysis in bug #22.
    i++;

Answer 14

在Perl5源代码库中，通常会在测试文件中引用错误及其关联的Trac编号。

这对我来说更有意义，因为为bug添加测试可以防止该bug再次被忽视。

可以在源代码中添加有关错误修复的注释吗？

14 个答案: