当我们在版本控制系统（例如 TFS）中注册代码时，我们需要制定编写注释的指南。
例如，当我们提交错误修复时，我们会创建一个评论“已修复错误#...”
我们试图就这个话题集思广益，但大多数想法带来的附加值太少。
我将不胜感激任何建议。
问问题
634 次
8 回答
7
通常，我们在我工作的地方所做的评论是对所做更改的快速概述。一些简短而简单的东西。
最初它似乎没有增加太多价值，但在回顾历史试图找出什么时候发生变化时会很有帮助（不仅仅是“错误#####”）。有几次我需要返回源代码控制历史来尝试查找特定行为或代码段何时发生更改，并且快速概览可以更容易地追踪可能发生的位置。如果您只是给出一个错误编号，那么您必须做更多的工作才能找到该基本信息（拉起错误跟踪器并找到错误）。
于 2009-05-12T20:55:39.513 回答
7
我对这个主题的（相当简洁的）指导是“记录你为什么要做出改变而不是什么”。
即，您不应该说“MyClass.cs 和 FooBar.cs 中的已修复错误”，因为该评论是相当不相关的——他们只需查看变更集即可找到这些详细信息。与 TFS 一样，将变更集链接到工作项意味着在注释中包含工作项引用是非常多余的。相反，一个简短的句子解释了更改的原因，例如“在编辑器中修复了潜在的 XSS 漏洞”，这是在查看大量更改集历史时最有用的内容。
于 2009-05-13T01:02:49.493 回答
4
对于将在发行说明中提及的更改，请在更改集注释或链接的错误报告（如果有）中包含建议的发行说明条目。
通过写出发行说明条目，您被迫退后一步，从用户的角度查看编辑。这鼓励您简洁地描述问题所在以及修复如何解决问题。
于 2009-05-12T21:42:28.313 回答
2
您可以将 TFS 配置为要求任何代码签入都具有与之关联的 TFS 任务。
在我工作的地方使用它的项目团队要求将所有错误和/或功能作为任务输入到 TFS 中 - 并且任何代码签入都与其适用的任务相关联。
评论也是必需的，但他们对您编写的内容没有任何严格的指导方针，除了要注意是否不需要将更改合并到另一个分支。
于 2009-05-12T20:59:39.693 回答
1
如果更改在某处有关联票证或错误，那么在这种情况下，编号和标题（带有链接）就足够了。
否则，只需说明您实施了哪些更改。定期评论指南适用，您可以查看一些流行的项目日志以查看好的示例。
于 2009-05-12T20:56:28.637 回答
1
在可能的情况下（例如在使用 TFS 进行错误跟踪和源代码控制时）将签入直接链接到适当的工作项。如果做不到这一点，请在变更集注释中添加工作项/错误 #。这是变更集注释的最低可接受级别。
签入注释应描述所做更改的意图，仅在必要时添加有关更改实现预期结果的方式的详细信息。一个好的起点是相应工作项的标题。
一两句话是评论的一个很好的目标长度。不要太笼统，评论毫无意义（例如“修复 xyz 中的错误”），但也不要在不必要的细节层下隐藏更改的意图。
于 2009-06-06T10:16:24.517 回答
0
如果可能的话，我喜欢包含对 bug 的引用（票证、问题、它的名称），因为这为更改提供了上下文和动机。另外，我喜欢尽量接近一行来回答“发生了什么变化”和“为什么”这样的问题。在发表评论时，我试图在 6 个月内回想我未来的自己，回顾日志、差异和票证，以了解我到底在想什么。进入太多细节似乎从来没有帮助。
于 2009-05-12T20:57:12.147 回答
0
+1 用于粘贴错误问题标题，该标题应该提供信息。
+1 说明原因，如果需要，除了错误标题。
+1 在您想通知客户时注意发布说明。
+1 用于集成 SCM、错误跟踪和 CI，并使它们在问题/错误上相互链接。
于 2010-04-09T11:32:29.960 回答