您是否对代码中的错误修复使用了特殊注释？

Question

我的一些同事对其错误修复使用了特殊评论，例如：

// 2008-09-23 John Doe - bug 12345
// <short description>

这有意义吗？ 你是否以特殊的方式评论错误修复？

请告诉我。

Answer 1

我没有这样的评论，源控制系统已经保留了历史记录，我已经能够记录文件的历史记录了。

我确实提出了一些评论，这些评论描述了为什么一些非显而易见的事情。因此，如果错误修复使代码不那么可预测和清晰，那么我解释原因。

Answer 2

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

Answer 3

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

  

[Bug-Id] xyz对话框问题。   将调整代码移动到abc和现在   稍后再说。

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

  

已在更改列表1234中修复。

     

将调整代码移动到abc和现在   稍后再说。

因为那时留下了一个好的历史标记。如果您想知道特定代码行是以某种方式存在的原因，您也可以轻松查看文件历史记录。一旦找到了代码行，就可以阅读我的提交注释，并清楚地看到它的错误以及我是如何修复的。

Answer 4

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

Answer 5

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

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

这样代码所有者，或者跟我进来的人，可以弄清楚发生了什么，如果有必要，他们可以与我取得联系。

（是的，不幸的是，他们通常没有源代码控制......对于我使用TFS跟踪的内部内容）

Answer 6

虽然这在当时看起来似乎是一个好主意，但它很快就会失控。使用源控制系统和错误跟踪器的良好组合可以更好地捕获此类信息。当然，如果有一些棘手的问题，描述情况的评论在任何情况下都会有所帮助，但不会有日期，名称或错误号。

我目前正在工作的代码库已经有20年了，他们似乎已经添加了很多像今年这样的评论。幸运的是，他们在90年代后期将所有内容转换为CVS后几年就停止了这样做。但是，整个代码中仍然存在这样的注释，现在的策略是“如果您直接使用该代码，则将其删除，否则将其留下”。它们通常很难遵循，特别是如果添加和删除相同的代码几次（是的，它会发生）。它们也不包含日期，但包含你需要在古老的系统中查找的错误号以查找日期，所以没有人这样做。

Answer 7

这样的评论是Subversion允许您在每次提交时键入日志条目的原因。这就是你应该放置这些东西的地方，而不是代码。

Answer 8

虽然我确实倾向于看到代码中有关于工作中的错误的一些评论，但我个人的偏好是将代码提交链接到一个错误。当我说一个我真的是指一个错误。之后，您可以随时查看所做的更改，并了解这些更改应用于哪些。

Answer 9

如果错误修复涉及的内容并不简单，我会这样做，但如果错误修复需要很长的解释，我会把它作为修复设计不好的标志。偶尔我必须解决一个无法改变的公共接口，因此这往往是这些评论的来源，例如：

// <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.

在其他情况下，源代码控制提交消息是我用来注释更改的内容。

Answer 10

这种评论风格在多开发人员环境中极具价值，在这种环境中，开发人员拥有一系列技能和/或业务知识（例如 - 无处不在）。

对于经验丰富的知识渊博的开发人员来说，改变的原因可能是显而易见的，但对于较新的开发人员而言，评论会让他们三思而后，在搞乱之前进行更多调查。它还可以帮助他们更多地了解系统的工作原理。

哦，以及关于“我刚把它放在源代码管理系统中”的经验说明评论：

如果它不在源中，则不会发生。

由于缺乏源控制软件，不正确的分支模型等，我无法计算项目源历史记录丢失的次数。 只有一个地方更改历史记录不能丢失 - 这就在源文件中。

我通常先将它放在那里，然后在我检查时剪切'n粘贴相同的注释。

Answer 11

如果代码得到纠正，评论就没用了，对任何人都没有兴趣 - 只是噪音。

如果错误未解决，则评论错误。那就有道理了。 :)所以如果你没有真正解决这个问题就留下这样的评论。

Answer 12

没有。我使用subversion并且总是输入我对提交更改的动机的描述。我通常不会用英语重述解决方案，而是总结所做的更改。

我参与了许多项目，他们在修复错误时在代码中添加了注释。有趣的是，也许并非巧合，这些项目要么没有使用任何形式的源控制工具，要么被强制要求管理层遵守这种惯例。

老实说，在大多数情况下，我并没有真正看到这样做的价值。如果我想知道改变了什么，我会看看颠覆日志和差异。

只是我的两分钱。

Answer 13

如果您在维护代码几年后添加类似的注释，那么您将无法阅读错误修复注释。

但是如果你把看起来正确（但有一个微妙的bug）的东西变成更复杂的东西，最好添加一个简短的注释来解释你做了什么，以便下一个维护这段代码的程序员不会改变它因为他（或她）认为你过于复杂的事情是没有充分理由的。

Answer 14

这样的评论通常更令人困惑，因为你没有关于原始代码看起来像或原始不良行为的背景。

一般情况下，如果您的错误修复现在使代码运行正确，只需简单地保留它没有注释。没有必要评论正确的代码。

有时错误修复使事情看起来很奇怪，或者错误修复正在测试一些与众不同的东西。然后有一个评论可能是合适的 - 通常评论应该引用你的bug数据库中的“bug号”。例如，您可能会有一条评论“Bug 123 - 当用户处于640 x 480分辨率时出现奇怪的行为”。

Answer 15

不，我不这样做，而且我讨厌像涂鸦一样涂鸦。可以在提交消息中跟踪错误号到版本控制系统，并通过脚本将相关提交消息推送到错误跟踪系统。我不相信它们属于源代码，未来的编辑只会让事情变得混乱。

Answer 16

请勿复制VCS将为您保留的元数据。日期和名称应由VCS自动添加。请求更改的故障单号，管理员/用户名等应该在VCS注释中，而不是代码中。

而不是：

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

我会这样做：

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

Answer 17

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

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

欢呼声，

罗布

Answer 18

当我在第三方库/组件中进行错误修正/增强时，我经常发表一些评论。如果我需要使用更新版本的库/组件，这样可以更轻松地查找和移动更改。

在我自己的代码中，我很少评论错误修正。

Answer 19

我不参与多人项目，但我有时会在单元测试中添加关于某个bug的评论。

请记住，没有错误，只是测试不足。

Answer 20

由于我做了尽可能多的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.

听起来很苛刻，但大多数自称“开发者”的人不应该发表其他言论。

Answer 21

要找到我们使用 DKBUGBUG 的特定评论 - 这意味着David Kelley的修复和审阅者可以轻松识别，Ofcourse我们将添加日期和其他VSTS错误跟踪号码等。