可以在源代码中添加关于错误修复的评论吗？

如果是这样，你在哪里画线？我和我的同事在这个问题上不同意。我见过这样的事情可以在源代码中添加关于错误修复的评论吗？

// fixes bug # 22

到

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

它是确定，如果变化是相当显著，并从根本上改变什么方法写怎么办？或者，您是否简单地更改方法的摘要文本以反映它现在的意图？

我的意见是，这个信息应该放在源代码管理中。有些人认为这很糟糕，因为那样会在源代码管理的上下文之外丢失（比如说切换系统并希望保留历史数据）。

来源

2009-12-09 esac

评论应该解释这些方法是如何工作的。

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

来源

2009-12-09 23:02:38

我的想法确切。 – 2009-12-09 23:04:52

不能同意更多。 – Davie 2009-12-09 23:08:51

这里说了什么。 – 2009-12-09 23:12:00

我们有几个这样的评论，但后来我们的Bugzilla服务器死了，我们重新开始在bug＃1，所以他们都没有意义。现在，我的首选方法是对该错误的简短解释。

来源

2009-12-09 23:01:45

假设的意见是不是多余的（经典i++; //increment i例子想到的），几乎从未有原因的争论对添加注释，不管是什么它涉及到。信息很有用。然而，最好是描述性的和简洁的 - 不要说“修正错误#YY”，而是添加类似“这用于x = 0失败，这里额外的逻辑阻止了”。这样，稍后查看代码的人可以理解为什么特定部分对正确功能至关重要。

来源

2009-12-09 23:02:48 Amber

...但太多的信息使用*少*，只是增加了噪音。 – 2009-12-09 23:04:40

因此，“假设评论不是多余的”介绍。该评论应该仍然与代码相关，但仅仅因为一个错误不再存在并不意味着警告其他人再次犯错误是没有用的。 – Amber 2009-12-09 23:06:12

而不是提到一个过去的bug，对于这个例子来说，“这可以防止x = 0时发生故障”。 – 2009-12-09 23:43:07

不可以。您应该保留有关错误的信息以及修复源代码外部错误的更改集。代码中的任何注释本身只应与代码的作用有关。其他任何东西都只是混乱。

来源

2009-12-09 23:03:31 tvanfosson

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

我的理由是可维护性 - 2（或10）年后，这个评论将不再有意义。在你上面的例子，我宁愿是这样的：

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

不同的是，它不依赖于一个错误，而是什么代码做什么。评论应该评论代码，而不是元信息，国际海事组织。

这个观点部分是因为我保持一个很老的代码库 - 我们有很多的评论不再有意义相关的bug修复或增强功能的请求，等....

来源

2009-12-09 23:03:59

我靠的FogBugz和在svn登记注释。虽然jeffamaphone说，如果你丢失了错误数据库，案例数字并没有多大意义，但它的效果很好。

将代码置入代码中的一个问题是，随着时间的推移，代码中将充斥着关于暂时不存在的问题的评论。通过在源代码控制签入注释中放置这些注释，您可以有效地将修补程序的相关信息与修正后的特定版本相关联，稍后可能会有所帮助。

来源

2009-12-09 23:04:02

我的观点是评论应该与开发者的意图相关，或者围绕算法/方法的'为什么'的亮点。

评论不应该包括修补时间。

来源

2009-12-09 23:04:13

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

例如，

/* 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是更好保持在源控制。您的代码中的评论应该是路标，以帮助未来的旅客在途中，而不是满足过程和跟踪。

来源

2009-12-09 23:04:41 erickson

+1。理想主义者会这样说：“评论应该解释这些方法是如何工作的，源代码控制解释了为什么要做出改变。”这忽略了这样一个事实，即当你阅读复杂的代码时，它有助于知道它为什么做了不明显的事情，提及影响它的写法的情况与解释这种情况的方式是一样的。 – Edmund 2009-12-09 23:14:03

那么示例注释正在解释该方法的工作原理。并带有一点历史背景。 – Martin 2009-12-10 10:27:51

一致认为，偶尔你必须在其中放置一些东西，这就解释了为什么你做的事情大部分时间看起来很愚蠢。 – jcollum 2010-02-21 23:39:25

我同意这些数据应放置在源代码管理或其他部分配置管理中。我曾经在代码库中发布过有关错误修复的信息，但我可以说它会在以后导致非常混乱的评论和代码。修复到位后六个月，你是否真的想知道一条线修复了一些长期以来的错误？当你需要重构代码时，你如何处理评论？

来源

2009-12-09 23:05:31 Andrew

像// fixes bug # 22 之类的东西本身就没有意义，需要采取补充措施，甚至可以了解它的含义以及它实现的角色。我认为一个简短的描述更合适，不管你使用的错误跟踪或源代码控制软件如何。

来源

2009-12-09 23:05:50 luvieere

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

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

它也可以作为一个标记，所以你可以找到你需要检查的代码是否升级到下一个版本的API。

来源

2009-12-09 23:07:48 ChrisF

我们在我的公司使用Team Foundation Server进行源代码管理，它可以让您将签入与bug报告绑定，因此我不会直接在代码中发表评论以达到相同的目的。

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

来源

2009-12-09 23:10:07

右键 - 一个*打开*错误的链接是不同的。 – 2009-12-10 19:48:03

所以很明显

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

来源

2009-12-10 19:47:38

另一个问题是：错误号是超链接。目前的代码和旧的错误通常是不相关的，但有时它们和链接是适当的。 – 2009-12-11 18:25:10

在Perl5的源代码库，通常指的错误，在测试的文件及其相关的Trac的数量。

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

来源

2009-12-11 00:17:13

可以在源代码中添加关于错误修复的评论吗？

回答

相关问题