你在代码中对bug修复使用了特殊注释吗?

我不会添加这样的评论,源代码管理系统已经维护了该历史记录,我已经能够记录文件的历史记录。

我确实发表了评论,描述了为什么要做一些不明显的事情。因此,如果错误修复使代码不那么可预测和清晰,那么我解释原因。

随着时间的推移,这些可能会积累并增加混乱。最好使代码清晰,为可能不明显的相关问题添加任何注释,并将错误详细信息保存在跟踪系统和存储库中。

我倾向于不在实际来源中发表评论,因为很难跟上最新进展。 但是,我确实在源代码管理日志和问题跟踪器中添加了链接注释。例如,我可能会在Perforce中做这样的事情:

[Bug Id]xyz对话框出现问题。 将尺码代码移动到abc,现在 稍后初始化。

然后,在我的问题跟踪器中,我将执行以下操作:

已在更改列表1234中修复。

将尺码代码移动到abc,现在 稍后初始化。

因为这样就留下了一个很好的历史标记。此外,如果你想知道为什么特定的代码行是某种方式,你可以查看文件历史记录。一旦你找到了代码行,你就可以阅读我的提交注释,清楚地看到它是针对哪个bug的,以及我是如何修复它的。

只有当解决方案特别聪明或难以理解时。

我通常会添加我的姓名、电子邮件地址和日期,以及对我更改内容的简短描述,这是因为作为一名顾问,我经常修改别人的代码。

// Glenn F. Henriksen (<email@company.no) - 2008-09-23
// <Short description>

这样,代码所有者或在我之后进来的人就可以弄清楚发生了什么,如果有必要,他们可以联系我。

(是的,不幸的是,他们往往没有源代码控制……对于内部内容,我使用TFS跟踪)

虽然这在当时看起来是个好主意,但很快就会失控。使用源代码控制系统和错误跟踪器的良好组合可以更好地捕获这些信息。当然,如果有什么棘手的事情发生,在任何情况下,描述情况的评论都会有所帮助,但日期、名称或错误号则不然。

我目前正在工作的代码库大约有20年的历史,他们似乎在几年前添加了很多这样的注释。幸运的是,在90年代末将所有东西都转换为CVS几年后,他们停止了这样做。然而,这样的注释仍然散布在整个代码中,现在的政策是“如果你直接处理该代码,请删除它们,否则请保留它们”。它们通常很难遵循,尤其是在多次添加和删除同一代码的情况下(是的,确实如此)。它们也不包含日期,但包含错误号,你必须在一个古老的系统中查找才能找到日期,所以没有人这样做。

这样的注释就是为什么Subversion允许您在每次提交时键入日志条目。这就是你应该把这些东西放在哪里,而不是放在代码中。

如果bug修复涉及一些不简单的事情,我会这样做,但如果bug修复需要长时间的解释,我通常会认为这表明修复设计得不好。有时,我不得不处理一个无法更改的公共界面,因此这往往是这类评论的来源,例如:

// <date> [my name] - Bug xxxxx happens when the foo parameter is null, but
// some customers want the behavior.  Jump through some hoops to find a default value.

在其他情况下,我使用源代码管理提交消息来注释更改。

虽然我确实倾向于在工作中看到一些关于代码中错误的评论,但我个人的偏好是将代码提交链接到一个错误。当我说一个时,我的意思是一个bug。之后,您始终可以查看所做的更改,并知道这些更改应用于哪个bug。

这种评论风格在多开发人员环境中非常有价值,在这种环境中,开发人员(例如,在任何地方)都有一系列技能和/或业务知识。

对于经验丰富、知识渊博的开发人员来说,更改的原因可能是显而易见的,但对于新的开发人员而言,这样的评论会让他们三思而后行,在动手之前做更多的调查。这也有助于他们更多地了解系统是如何工作的。

哦,还有一条关于“我刚刚把它放在源代码控制系统中”的评论:

如果它不在源头,它就不会发生。

由于对源代码控制软件缺乏经验、分支模型不正确等原因,我无法计算项目的源代码历史丢失的次数。这是 只有一个地方是变化历史 不能丢失 -这在源文件中。

我通常先把它放在那里,然后在签入时剪切并粘贴相同的评论。

不,我不喜欢,我讨厌在代码上乱涂乱画。Bug编号可以在提交给版本控制系统的提交消息中跟踪,也可以通过脚本将相关的提交消息推送到Bug跟踪系统中。我不认为它们属于源代码,因为未来的编辑只会让事情变得混乱。

通常,这样的注释更令人困惑,因为您没有关于原始代码外观或原始不良行为的上下文。

一般来说,如果你的bug修复现在使代码正确运行,只需不加注释就可以了。不需要注释正确的代码。

有时,bug修复会让事情看起来很奇怪,或者bug修复是在测试一些不同寻常的东西。然后,发表评论可能是合适的——通常评论应该引用你的bug数据库中的“bug编号”。例如,您可能会有一条评论,上面写着“Bug 123-当用户在640乘480的屏幕分辨率下时的奇怪行为”。

如果你在维护代码几年后添加这样的注释,你会有太多的bug修复注释,以至于你无法阅读代码。

但是,如果你将看起来正确的东西(但有一个微妙的错误)更改为更复杂的东西,最好添加一个简短的注释来解释你所做的事情,这样下一个维护这段代码的程序员就不会因为他(或她)认为你没有充分的理由而将其更改回来。

不。我使用subversion,并总是输入我做出改变的动机的描述。我通常不会用英语重述解决方案,而是总结所做的更改。

我参与过许多项目,在修复错误时,他们会在代码中添加注释。有趣的是,可能并非巧合的是,这些项目要么没有使用任何类型的源代码控制工具,要么被管理层强制遵循这种惯例。

老实说,在大多数情况下,我真的看不出这样做的价值。如果我想知道发生了什么变化,我会查看subversion日志和差异。

只有我的两分钱。

如果代码被纠正了,注释就毫无用处,任何人都不会感兴趣——只是噪音。

如果bug没有解决,评论就是错误的。那么,这是有道理的。:)所以,如果你没有真正解决这个bug,就留下这样的评论。

为了定位我们使用的特定评论 DKBUGBUG -这意味着David Kelley的修复和审阅者可以很容易地识别,当然,我们会在其中添加Date和其他VSTS错误跟踪号等。

不要复制你的VCS将为你保留的元数据。日期和名称应由VCS自动添加。请求更改的工单编号、经理/用户名等应在VCS注释中,而不是代码中。

与其这样:

//$DATE$NAME$TICKET //对下一个可怜的灵魂的有用评论

我会这样做:

//对下一个可怜的灵魂的有用评论

如果代码位于实时平台上,远离对源代码管理存储库的直接访问,那么我将添加注释,以突出显示作为实时系统错误修复的一部分所做的更改。

否则,您在签入时输入的消息不应包含您需要的所有信息。

干杯,

抢

当我在第三方库/组件中进行错误修复/增强时,我经常发表一些评论。如果我需要使用较新版本的库/组件,这使得查找和移动更改变得更加容易。

在我自己的代码中,我很少注释bug修复。

我不从事多人项目,但我有时会在单元测试中添加关于某个bug的注释。

记住,没有bug,只有测试不足。

由于我尽可能多地进行TDD(其他一切都是社交自杀,因为其他所有方法都会迫使你无休止地工作),我很少修复bug。

大多数时候,我会在代码中添加这样的特殊注释:

// I KNOW this may look strange to you, but I have to use
// this special implementation here - if you don't understand that,
// maybe you are the wrong person for the job.

听起来很刺耳,但大多数自称“开发人员”的人不值得再多说了。