版本控制注释的最佳实践

Question

关于评论代码的讨论很多，但是如何评论签到？

我发现这篇博文： http://redbitbluebit.com/subversion-check-in-comment-great-practices/

作为正在整理发行说明的人，我正在寻找使这项工作更轻松的方法。

目前，我们使用<Begin_Doc>...<End_Doc>定义了我们自己的方案，用于发布给我们软件客户的任何内容。但即使对于内部的东西，我也想知道每个变化的“原因”。

Answer 1

每个功能都有一个故障单/问题/ bugreport / task /无论你打电话给它，故障单号总是在登记注释中引用。这给出了背景。

Answer 2

我建议不要使用/重载你的版本控制系统。我建议问题跟踪软件更合适。

首先，让开发人员在需求文档或问题/缺陷系统中的提交消息中添加所有上下文和重复信息似乎不合适。

您可以使用工具收集提交注释中的相关修订/问题编号，然后从其他存储库中收集这些数据，但我认为基本上使您的修订工具成为面向外部的工具是错误的。

您需要定义源/版本存储库/ SVN是什么 - 它是用于管理源文件，还是用于编写发行说明。我认为它不应该超载。

Answer 3

我们试着保持简单：写一个句子来描述你提交的更改。如果开发人员需要两个或更多的句子来描述提交，那么也许提交是两个不相关的部分工作。当这样的提交最终在版本控制中时，很难单独恢复修复。

我们希望在提交注释中包含的另一条信息是提交修复/实现的缺陷/功能号。并非我们所做的所有工作都与问题跟踪系统中的缺陷有关，因此这不是强制性的。

我们在提交注释中提供的最后一条信息是一个代码审阅者的名称。这是在提交之前对更改进行完整性检查的人。

Answer 4

我推荐功能评论。评论应该总结改变的内容。如果有什么改变，为什么。每个提交都应该是可以解释的，如果你不能清楚地解释它，你可能不应该检查它。

使用源代码控制日志时最重要的事情是它们可以确定更改的时间和内容。功能越多，越详细越好。提交应该是一口大小的，可以用一口大小的评论来解释。

我个人喜欢这种风格：

更新错误记录系统。

1. 使用正则表达式添加了遗留错误解析例程以获取旧版错误代码。
2. 更改了数据库错误消息中的文本，以更正拼写错误。
3. 删除已注释掉的代码段，因为它们已不再使用。

Answer 5

关键是你要对评论做些什么。如果您正在创建发行说明，那么您可以按照建议进行操作。但是，我建议您在其他地方跟踪发行说明，例如在项目管理或错误跟踪工具中。

至于与开发者有关的评论，我们一般要求人们解释他们正在做什么，一句话解释。它不需要太正式，主要是因为如果它是人们会反对它。另外，如果您知道是谁做的，并且您有快速评论，那么您通常可以追溯问题并找到该人。

同样，如果您使用FogBugz之类的工具，则可以将SVN签到链接到案例编号。这意味着您可以查看案例以获得完整的讨论，评论，屏幕截图等。这比您在签到评论中输入的信息要多得多。

Answer 6

同意Remembrance，但您还应该写一些关于为什么以您的方式实施更改/错误修复的内容。 如果您经常在办理登机手续时相信，您还应该包括TO DO，以便让您的同事完成任务。

Answer 7

让我的变化变小有助于：我可以通过这种方式提供我的更改的详细说明。

签入评论应该是开发人员想要的信息：这包括重构，代码背后的动机等。

Answer 8

在我们的项目中，我们始终主张提供有关提交内容的一些细节，并协助不必重复信息，例如我们使用Trac的问题并集成我们的存储库。优点是您可以在注释中引用问题单，并仅说明执行的工作的分辨率或步骤。然后，Trac会自动将参考编号链接到原始编号，并将您的提交消息作为注释应用于问题。然后，当您想要查看已完成的工作时，您只需阅读Trac中的问题并获得完整的上下文。

关于发行说明，我们发现在发布中获取问题列表并使用提交信息作为注释的基础已经正常工作。通常，您不会在其中包含原始提交消息的发行说明，因为您的客户并不真正关心可能包含在评论中的每一个小变化甚至细节级别。因此，您通常需要进行大量编辑，以突出显示该版本中实施的主要更改和错误修复。

Answer 9

我会说尝试遵循更改日志样式。第一行应为简短摘要，并包括问题/票号（如果有）。这可能后跟一个空行，具体取决于您的VCS如何处理多行提交消息，然后是更全面的多行描述。我会说强加任何严格的格式都是不合理的，因为它会阻止频繁的提交，但只要重要的提交（关闭问题，或重大改变）就这样完成你应该没问题。

如果您使用Trac或roundup + svn集成之类的东西，它可以从提交消息中挑选出问题编号。我总是将这些放在第一行，因为它们非常有用。

Answer 10

编辑：鉴于这是迄今为止我最倾向的答案，我认为值得强调最后一段中隐藏的内容：我是唯一的所有者。我拥有这些项目的100％所有权，不与其他开发人员合作。在一家拥有多个开发人员的商店里，我在这个答案中所说的一切都可能完全不合适。

我在这里订阅了DRY。

我几乎从不在我的提交中添加评论。评论几乎总是在重复自己。问题“这个提交中发生了什么变化”的答案？几乎总是在差异中。

当我正在查看文件时，我问“这里到底发生了什么？”，我要做的第一件事就是看看之前版本的差异。 90％的时间答案是显而易见的，要么是因为代码不言自明，要么是因为我在代码中注释了一些不言自明的东西。如果不是，我将文件的修改日期与错误跟踪系统相关联，答案就在那里。

这总是有效的。它有时需要一些调查来解决问题，因为我没有充分评论我的代码。但是我从来没有找不到相应的答案。

我唯一一次在提交日志中添加注释是因为我知道差异对我没有帮助。例如，当我对一个类的成员进行排序时：在这种情况下，差异就是告诉我的唯一一件事就是发生了很大的事情。当我这样做时，我会在修复后立即提交文件。没有合适的地方来评论文件中该范围的更改，因此我添加了一个注释，表明此版本中唯一的更改是重新排序成员。

（“为什么你不会在文件顶部的修订历史记录中评论这样的更改？”你可能会问。我没有在我的文件顶部保留修订历史记录。这是一个可怕的，打破一生一生的习惯，我从来没有后悔过。修订历史是Subversion。）

如果我没有100％的项目所有权，可能会有所不同。将提交与错误修复相关联可能太难了。培训其他开发人员编写一种可以有效依赖版本控制的风格可能太难了。我得看看。