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

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

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

如果你写的是正确的,那么添加一个关于错误修复的注释是一个好主意。

例如,

/* 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 是 更好地保存在源代码管理中。代码中的注释应该是帮助未来的旅居者上路的路标,而不是满足流程和跟踪的要求。

不可以。您应该保留关于bug的信息以及修复源代码外部bug的更改集。代码本身的任何注释都应该只与代码所做的相关。其他的都是乱七八糟的。

我个人认为评论应该是关于代码本身的,而不是关于错误修复的。

我的原因是可维护性——2(或10)年后,这个评论将不再有意义。在上面的示例中,我更喜欢这样的内容:

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

不同的是,它与 缺陷 而是代码在做什么。评论应该是对代码的评论,而不是meta-info,imo。

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

我们有一些这样的评论,但是我们的Bugzilla服务器死了,我们在bug_1重新启动,所以它们都毫无意义。对这个错误的简短解释是我现在的首选方法。

类似的东西 // fixes bug # 22 它本身就毫无意义,甚至需要补充步骤来了解它的含义以及它所扮演的角色。在我看来,一个简短的描述更合适,不管你可能使用的是错误跟踪或源代码控制软件。

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

如果这涉及到在修复原始bug时添加注释,则执行该操作。

它还可以作为标记,这样您就可以找到需要检查是否升级到下一个版本的API的代码。

假设评论不是多余的(经典 i++; //increment i 举个例子),几乎没有理由争辩 反对 添加注释,不管它与什么相关。信息是有用的。但是,最好是描述性的和简洁的——不要说“修复了错误yy”,而是添加一些类似“这在x=0时失败,这里额外的逻辑可以防止这种情况”。这样,以后查看代码的人就可以理解为什么特定的部分对于正确的功能至关重要。

我在SVN中依赖FogBugz和签到评论。效果很好,不过正如Jeffamaphone所说,如果你丢失了你的bug数据库,那么案例号就没有什么意义了。

在代码中添加注释的一个问题是,随着时间的推移,您的代码中会充满关于暂时不存在的问题的注释。通过将这些注释放在源代码管理签入注释中,您可以有效地将有关修复的信息与修复的特定版本联系起来,这在以后可能会有所帮助。

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

评论不应该围绕着及时修复。

我同意这些数据应该放在源代码管理或其他部件配置管理中。我在代码库中工作过,代码库将关于错误修复的信息放在注释中,我可以说这会导致非常混乱的注释和代码。修复完成6个月后,您真的想知道有关修复某个很久以前的bug的行吗?当需要重构代码时,如何处理注释?

我们使用Team Foundation Server在我的公司进行源代码管理,它允许您在错误报告中签入签入,所以我不会直接在代码中向服务器发送注释。

然而 ,在我将代码实现为.NET框架或第三方库中的bug的解决方案的情况下,我希望将URL放在Microsoft TechNet日志或描述bug及其状态的网站上。

所以很明显

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

在Perl5源代码存储库中,常见的错误是指测试文件中的错误及其关联的trac编号。

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