Language agnostic 在源代码中添加关于bug修复的注释可以吗？

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

// fixes bug # 22

到

如果更改相当重要，并且从根本上更改了编写方法的目的，那么可以吗？或者您只是简单地更改该方法的摘要文本以反映它现在要做的事情

---

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

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

注释应该解释这些方法是如何工作的

---

源代码管理解释了更改的原因。

假设注释不是多余的（经典的

i++；//increment i

示例浮现在脑海中），几乎没有理由反对添加注释，不管它与什么相关。信息是有用的。但是，最好是描述性的和简洁的-不要说“修复了bug#YY”，而是添加一些类似于“x=0时这通常会失败，这里的额外逻辑阻止了这一点”。这样，稍后查看代码的人就可以理解为什么某个特定部分对于正确的功能至关重要。

否。您应该将有关错误的信息和修复错误的更改集保留在源代码外部。代码本身中的任何注释都应该只与代码正在执行的操作相关。其他任何东西都是杂乱无章的。

我个人认为评论应该是关于代码本身，而不是关于bug修复

我这样做的原因是可维护性——2（或10）年后，这一评论将不再有意义。在您上面的示例中，我更喜欢以下内容：

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

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

---

这部分是因为我维护了一个非常旧的代码库——我们有很多与bug修复或功能增强请求相关的注释，等等……

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

---

在代码中添加注释的一个问题是，随着时间的推移，您的代码中会充斥着关于已经不存在一段时间的问题的注释。通过将这些注释放在源代码管理签入注释中，可以有效地将有关修复程序的信息绑定到修复程序的特定版本，这在以后可能会有所帮助。

我的观点是，注释应该与开发人员的意图相关，或者与算法/方法相关的“为什么”的重点

---

评论不应该围绕着及时的修复。如果你写的是正确的，那么添加关于修复bug的评论是个好主意

比如说,

/* 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! */

---

像

修复bug#22

这样的东西最好保存在源代码控制中。代码中的注释应该是路标，以帮助未来的旅居者，而不是满足流程和跟踪要求。

我同意应将此类数据置于源代码管理或其他部件配置管理中。我曾经在代码库中工作过，这些代码库将有关错误修复的信息放在注释中，我可以说这会导致以后的注释和代码非常混乱。在修复完成六个月后，您真的想知道关于一条线路修复一些早已过时的bug的情况吗？当您需要重构代码时，如何处理注释？

类似于

//修复bug#22

---

它本身是毫无意义的，甚至需要补充步骤来了解它的含义和作用。在我看来，简短的描述更合适，无论您可能使用的是错误跟踪软件还是源代码控制软件。

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

如果这涉及到在修复原始bug时添加注释，那么就这样做

---

它也可以作为一个标记，这样你就可以找到你需要检查的代码，如果你升级到下一个版本的API。

< P>我们在我的公司使用Team Foundation Server作为源代码控制，它可以让你把一个签入到一个bug报告中，所以我不会把代码直接注释到服务器上。 然而，在我将代码作为.NET framework或第三方库中缺陷的解决方法的情况下，我喜欢在Microsoft TechNet日志或网站的URL中添加一个标记，以描述缺陷及其状态。

显然如此

    // fix bug #22
    i++;

这不是有效的沟通

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

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

如果可能对未来的读者有所帮助，请包括bug编号

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

有时重要的对话会记录在bug跟踪系统中，有时bug会导致关键的洞察，从而改变代码的形状

    // 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++;

---

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

---

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

…但是太多的信息是无用的，只会增加噪音。因此“假设注释不是多余的”“导言。注释应该仍然与代码相关，但仅仅因为一个bug不再存在并不意味着警告其他人不要再次犯错误是没有用的。与其说是指过去的bug，不如说（在本例中），“这可以防止在

    // 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++;