当我们在版本控制系统（例如TFS）中注册代码时，我们需要制定编写注释的指南。
例如，当我们提交错误修正时，我们会创建一个评论“修复错误＃...”
我们试图就这一主题进行头脑风暴，但大多数想法带来的附加价值太小。
对此我有任何建议。
答案 0 :(得分：7)
通常，我工作的评论是对所做更改的快速概述。简短而简单。
最初可能似乎没有增加太多价值，但在回顾历史时试图找到变化的东西（远远超过“bug #####”）可能会非常有用。有几次我需要回到源代码控制历史记录中来尝试查找特定行为或代码片段何时更改，并且快速概述可以更容易地跟踪可能的位置。如果您只是提供一个错误号，那么您必须做更多工作才能找到基本信息（启动错误跟踪器并找到错误）。
答案 1 :(得分：7)
关于这个主题的我（相当简单）的指导是“记录为什么你正在做出改变而不是什么。”
即。你不应该说“修复了MyClass.cs和FooBar.cs中的错误”，因为这个评论是相当无关紧要的 - 他们可以查看变更集来查找这些细节。与TFS同样，将变更集链接到工作项意味着在评论中包含工作项引用是非常多余的。相反，在查看变更集的重要历史时，用一个简短的句子来解释变更的原因，例如“编辑器中固定的潜在XSS漏洞”是最有用的内容。
答案 2 :(得分：4)
对于将在发行说明中提及的更改包含建议的发行说明条目，可以在变更集注释中或链接的错误报告中（如果有）。
通过写出发行说明条目，您不得不退后一步，从用户的角度来看编辑。这鼓励您简明扼要地描述问题所在以及解决方案如何解决问题。
答案 3 :(得分：2)
您可以将TFS配置为要求任何代码签入都有与之关联的TFS任务。
在我工作的地方使用它的项目团队要求将所有错误和/或功能作为任务输入到TFS中 - 并且任何代码签入都与它适用的任务相关联。
评论也是必需的，但是对于您所写的内容没有任何严格的指导，除非要注意是否需要将更改合并到另一个分支。
答案 4 :(得分：1)
如果更改在某处有错误的关联票证或错误，那么数字和标题（带链接）就足够了。
否则只说明您实施了哪些更改。定期评论指南适用，您可以查看一些热门项目日志以查看好的示例。
答案 5 :(得分：1)
如果可能（例如，当使用TFS进行错误跟踪和源代码管理时）将签入直接链接到适当的工作项。如果做不到这一点，请在变更集注释中添加工作项/ bug＃。这是变更集评论的最低可接受水平。
签入评论应描述所做更改的目的，仅在必要时添加有关更改实现所需结果的方式的详细信息。一个好的起点是适当的工作项目的标题。
一个或两个句子是评论的良好目标长度。不要太笼统，评论毫无意义（例如“修复xyz中的错误”），但不要在不必要的细节层次下隐藏更改的意图。
答案 6 :(得分：0)
我喜欢在可能的情况下包含对错误（票证，问题，所谓的）的引用，因为它提供了更改的背景和动机。此外，我想尽可能地回答问题已经发生了什么变化以及为什么尽可能接近一行。在做评论时，我试着在6个月内考虑我未来的自我，回顾日志，差异和票证，以了解我在想什么。进入太多细节似乎从来没有帮助。
答案 7 :(得分：0)
+1用于粘贴错误发布标题，这应该是提供信息的。
+1为文档原因，如果需要除了bug标题。
+1，以便了解发布说明，了解何时通知客户。
+1用于集成SCM，错误跟踪和CI，并使它们在问题/错误上相互链接。