有很多关于评论代码的讨论，但是评论签入怎么样？
我发现这篇博文： http ://redbitbluebit.com/subversion-check-in-comment-great-practices/
作为整理发行说明的人，我正在寻找使这项工作更容易的方法。
<Begin_Doc>...<End_Doc>目前，我们为应该发布给我们的软件客户的任何内容定义了自己的方案。但即使是内部的东西，我也想知道每次更改的“原因”。
问问题
5084 次
10 回答
22
每个功能都有一个工单/问题/错误报告/任务/无论你叫什么，工单号总是在签入注释中引用。这给出了上下文。
于 2008-11-26T18:46:52.883 回答
9
我建议不要为此使用/重载您的版本控制系统。我建议问题跟踪软件更合适。
一方面，让开发人员在已经在需求文档或问题/缺陷系统中的提交消息中添加所有上下文和重复信息似乎是不合适的。
您可以使用工具来收集提交评论中的相关修复/问题编号，然后从您的其他存储库中收集这些，但我认为基本上使您的修订工具成为面向外部的东西是错误的。
您需要定义源/版本存储库/SVN 是什么 - 是用于管理源文件，还是用于编写发行说明。我认为它不应该超载。
于 2008-11-26T18:51:19.880 回答
5
我们尽量保持简单：写一句话来描述您正在进行的更改。如果开发人员需要两个或更多句子来描述提交，那么提交可能是两个不相关的工作。当这样的提交最终进入版本控制时，很难单独恢复修复。
我们喜欢在提交评论中包含的另一条信息是提交修复/实现的缺陷/功能编号。并非我们所做的所有工作都与我们的问题跟踪系统中的缺陷有关，因此这不是强制性的。
我们在提交注释中添加的最后一条信息是一位代码审阅者的姓名。这是在提交发生之前对更改进行完整性检查的人。
于 2008-11-26T20:36:51.600 回答
3
我推荐功能性评论。评论应概述更改的内容。如果有什么改变了，为什么。每个提交都应该是可解释的，如果你不能清楚地解释它，你可能不应该检查它。
使用源代码控制日志时要记住的最重要的事情是它们可以确定何时更改以及更改了什么。功能越多，越详细越好。提交应该以一口大小的形式进行，可以用一口大小的注释来解释。
我个人的喜好是这样的风格：
更新了错误记录系统。
- 添加了使用正则表达式的遗留错误解析例程来获取遗留错误代码。
- 更改了数据库错误消息中的文本，以纠正拼写错误。
- 删除了注释掉的代码部分，因为它们不再被使用。
于 2008-11-26T20:35:43.177 回答
2
关键是你要对评论做什么。如果您正在创建发行说明，那么您可以按照您的建议进行操作。但是，我建议您在其他地方跟踪发布说明，例如在项目管理或错误跟踪工具中。
至于开发者相关的评论，我们一般会要求人们解释他们在做什么，一句话解释。它不需要太正式，主要是因为如果它是人们会反对它。另外，如果你知道是谁做的，并且你有一个快速的评论，你通常可以追溯问题并找到这个人。
同样，如果您使用FogBugz 之类的工具，您可以将 SVN 签入链接到案例编号。这意味着您可以查看案例以获取完整的讨论、评论、屏幕截图等。这比您在签入评论中输入的信息要多得多。
于 2008-11-26T18:52:17.740 回答
2
同意 Remembrance，但您还应该写一些关于您为什么以您的方式实施更改/错误修复的内容。如果您相信经常签到，您还应该包括待办事项，以使您的一位同事能够完成任务。
于 2008-11-26T18:54:35.410 回答
1
使我的更改很小有帮助：我可以通过这种方式提供我的更改的详细描述。
签入注释应该是开发人员想要的信息：这包括重构、代码背后的动机等。
于 2008-11-26T20:36:13.520 回答
1
在我们的项目中，我们总是提倡提供一些关于提交的细节，并帮助避免重复信息，例如我们使用 Trac 和集成我们的存储库的问题。优点是您可以在评论中引用问题单，并仅说明已执行的解决方案或工作步骤。然后，Trac 会自动将参考编号链接到原始问题编号，并将您的提交消息作为对问题的评论应用。然后，当您想查看已完成的操作时，您可以简单地阅读 Trac 中的问题并了解完整的上下文。
关于发布说明，我们发现在发布中获取问题列表并使用提交信息作为评论的基础效果很好。通常，您不会有包含原始提交消息的发行说明，因为您的客户并不真正关心每一个微小的变化，甚至不关心评论中可能包含的详细程度。因此，您通常需要进行大量编辑以突出显示该版本中实现的主要更改和错误修复。
于 2008-12-03T20:57:25.613 回答
0
我会说尝试遵循变更日志样式。第一行应该是一个简短的摘要，并包括问题/票号（如果有）。根据您的 VCS 如何处理多行提交消息，这可能后跟一个空行，然后是更完整的多行描述。我会说强加任何严格的格式是不合理的，因为它会阻止频繁提交，但只要以这种方式完成重要的提交（那些关闭问题或重大更改）你应该没问题。
如果您使用 Trac 或 roundup + svn 集成之类的东西，它可以从提交消息中挑选出问题编号。我总是把这些放在第一行，因为它们非常有用。
于 2008-11-26T18:53:54.537 回答
-3
编辑：鉴于这是迄今为止我最不赞成的答案，我认为值得强调最后一段中隐藏的内容：我是独资经营者。我对这些项目拥有 100% 的所有权，并且不与其他开发人员合作。在拥有多个开发人员的商店中，我在此答案中所说的一切可能完全不合适。
我在这里订阅 DRY，就像在所有事情上一样。
我几乎从不为我的提交添加评论。评论几乎总是在重复我自己。“这次提交发生了什么变化”这个问题的答案？几乎总是在差异中。
当我查看一个文件并问“这里到底发生了什么？”时，我做的第一件事就是查看与前一个版本的差异。90% 的情况下，答案是立即显而易见的，要么是因为代码不言自明，要么是因为我在代码中注释了一些不言自明的东西。如果不是，我将文件的修订日期与错误跟踪系统相关联，答案就在那里。
这总是有效的。有时需要进行一些调查才能弄清楚，因为我没有充分评论我的代码。但我从来没有很快找到答案。
我在提交日志中添加评论的唯一一次是当我知道差异对我没有帮助时。例如，当我对一个类的成员进行排序时：在这种情况下，差异唯一会告诉我的是发生了非常大的事情。当我这样做时，我会在修复它后立即提交文件。没有合适的地方来评论文件中该范围的更改，因此我添加了一条注释，大意是此 rev 中的唯一更改是重新排序成员。
（“你为什么不在文件顶部的修订历史中评论这样的更改？”你可能会问。我没有在我的文件顶部保留修订历史。那是一个可怕的，打破 -一生的习惯改变，我从来没有后悔过。修订历史是颠覆。）
如果我没有 100% 的项目所有权，情况可能会有所不同。将提交与错误修复关联起来可能太难了。培训其他开发人员编写代码以使其能够有效地依赖版本控制可能太难了。我得看看。
于 2008-11-26T20:22:35.780 回答