Version control 对sourcecontrol中变更集的良好评论

在版本控制系统（如TFS）中注册代码时，我们需要制定编写注释的指导原则

例如，当我们提交错误修复时，我们会创建一条注释“Fixed bug#…”

我们试图就这个话题进行头脑风暴，但大多数想法带来的附加值太少

---

如果您能给我一些建议，我将不胜感激。

一般来说，我们在我工作的地方所做的评论都是对所做更改的快速概述。简短的东西

---

起初，它似乎没有增加多少价值，但当回顾历史，试图发现什么时候发生了变化时，它会非常有帮助（不仅仅是“bug”）。有几次，我需要回到源代码管理历史中，尝试找出某个特定行为或代码段何时发生了更改，快速概述可以使跟踪可能发生的更改变得更加容易。如果您只是给出了一个bug编号，那么您必须做更多的工作来查找基本信息（调出bug跟踪器并找到bug）。

如果更改在某个地方有相关联的票证或bug，在这种情况下，编号和标题（带链接）就足够了

---

否则，请说明您实施了哪些更改。如果可能的话，你可以查看一些流行的项目日志以查看好的例子。

我喜欢引用bug（罚单、问题，无论它叫什么），因为这提供了更改的背景和动机。此外，我喜欢尽可能用一行字来回答问题：发生了什么变化以及为什么发生了变化。当我发表评论时，我试着想想我未来6个月的自我，回顾日志、差异和票证，了解我到底在想什么。太多的细节似乎没有帮助。

您可以将TFS配置为要求任何代码签入都与TFS任务关联

在我工作的地方使用它的项目团队要求将所有bug和/或特性作为任务输入TFS中，并且任何代码检入都与它应用的任务相关联

---

也需要注释，但他们没有任何严格的指导方针来指导您的写作，除非注意是否不需要将更改合并到另一个分支机构。

对于将在发行说明中提及的更改，包括建议的发行说明条目，在变更集注释或链接的错误报告（如果有）中

通过编写发行说明条目，您不得不后退一步，从用户的角度查看编辑。这鼓励您简明扼要地描述问题是什么，以及修复程序如何解决问题。

我（相当精练的）关于此主题的指导是“记录为什么要进行更改，而不是更改什么。”

也就是说，你不应该说“修复了MyClass.cs和FooBar.cs中的bug”，因为那条评论是相当不相关的——他们只需查看变更集就可以找到这些细节。与TFS一样，将变更集链接到工作项意味着在注释中包含工作项引用是非常多余的。相反，在查看大量变更集历史记录时，最有用的是用一句简短的话解释变更原因，如“编辑器中修复了潜在的XSS漏洞”。

在可能的情况下（如使用TFS进行错误跟踪和源代码控制时），将签入直接链接到适当的工作项。否则，在变更集注释中添加工作项/bug。这是变更集注释的最低可接受级别

签入注释应描述所做更改的意图，仅在必要时添加有关更改实现预期结果的方式的详细信息。一个好的起点是适当工作项的标题

---

一两句话是评论的好目标长度。不要太笼统——评论毫无意义（例如“修复了xyz中的一个bug”），但也不要在不必要的细节层下隐藏更改的意图。

+1用于粘贴bug问题标题，该标题应提供信息

+1说明原因，如果需要，除了错误标题

+1当您想通知客户时，请注意发布说明

---

+1用于集成SCM、bug tracking和CI，并使它们在问题/bug上相互链接。

请将此社区wiki设置为主观。我会将bug标题和bug编号粘贴到注释中：理想情况下，bug已经有了一个信息标题。为什么要添加编号，工作项链接不够？（或者您没有使用TFS进行错误跟踪？）