4

COMMENTING提交的最佳实践是什么？

一点背景。

  • 我们所有的项目都使用版本控制（Subversion / SVN / Git），
  • 他们中的大多数都被 2 个或更多的开发人员所触动，
  • 我们使用 Springloops 来托管我们的版本控制，因为它“正常工作”并且比让内部开发人员维护它更便宜，
  • 因为我们的许多客户都有特殊的设置，而且为多个用户设置这些环境是可行的，所以我们很少为本地开发环境而烦恼。大多数客户在云中都有一个开发位置，然后是一个实时位置。Springloops 被配置为自动将每个提交推送到开发服务器，并且开发人员必须手动推送到实时位置。

我们的政策是评论您提交的所有内容，但我们中的一些人最近反对这个想法。

评论所有内容的问题是双重的，它的工作量更大，用处也更少。以下是我们看到的问题：

  1. 它鼓励人们发表评论，涵盖已经在版本控制中的内容（即我将第 42 行更改为废话）。您可以进行比较以获得相同的信息！

  2. 或者，它会用无用的评论填充您的评论流，如果您想搜索评论，这将是一个巨大的痛苦。

    • IE8 的边距问题
    • IE8 中对边距的另一个修复
    • 恢复上一个修复并在 IE8 中尝试其他有边距的东西

这些事情中的任何一个都只会增加很多时间，并且不会增加任何价值。仅当评论足够具体且足够稀有以至于您可以扫描所有内容时，评论才有用。

我们被告知 Git 以比 Subversion 更智能的方式处理这个问题，我们愿意改变，显然拥有一个本地开发环境并且只提交批量更改也会有所帮助，但根据我们的用例，这可能是效率方面的净损失。

我很想听听人们评论提交的最佳实践是什么，感谢您的任何反馈！

4

4 回答 4

9

Git 不会为你解决问题；你需要回答这个“简单”的问题：如何增加评论的价值？

一些指导方针：

  1. 不要在评论中提及提交本身显而易见的任何内容（例如更改了哪一行）。现代工具将在屏幕上并排显示提交消息和提交。重复工作是没有意义的。

  2. 相反，解释你为什么做出改变——这通常并不明显。是错误报告吗？包括错误的 ID。是不是你发现了什么？

  3. 如果您发现自己经常处于必须在一次提交中提交多个修复的情况，那么您需要学会集中注意力。更改代码时不要随心所欲。做一件事，完成它，提交它。然后做接下来的事情。

    如果您在途中偶然发现某事，请记下（在纸上或在您一直悬停在屏幕一角的额外文本编辑器中）。不要总是打扰你的工作！多任务/递归代码编辑对质量和压力水平有严重影响。

你仍然会得到一长串“Fixed IE8 margin”提交，但这本身不是问题。当您说“我们要搜索评论”时，您必须想出一种方法将有用的信息放入评论中，以使搜索变得合理。例如，始终对错误 ID 使用相同的格式。纯文本不利于搜索，尤其是应该简洁的提交消息。

只是省略评论不是解决方案，它要么是懒惰，要么是反社会的标志（“谁在乎别人是否对此有问题？”）或训练不佳（“我不知道该写什么”）。

第一个和最后一个可以通过训练来解决。第二个是摆脱风险（即解雇那个人）。

世界上没有任何版本控制工具可以帮助您。

于 2012-08-17T13:53:38.373 回答
2

我的经验法则是，如果我不能用不到两句话总结提交的更改，那么距离上次提交的时间太长了。

至于在那句话中写什么，我从不说任何特定于行或特定于文件的内容，因为该信息嵌入在提交中。我通常会用简单的英语提到具体的变化，就像我会向不属于该项目的人解释它一样。

这非常有效，因为无论是我还是其他人几个月后，他们都可以阅读提交日志，就像项目如何开发的故事一样。我什至写过一些只是复制和粘贴我的提交日志的博客文章。

于 2012-08-17T13:52:44.530 回答
2

我的理念是：

  1. 尽快提交
  2. 提交前更新和构建
  3. 提交前的差异
  4. 不要破坏 BUILD：提交后更新并测试 BUILD

所有这些都是每个团队成员都必须遵守的个人纪律问题。如果人们破坏了构建，构建经理会“鼓励”在午夜唤醒他们。

于 2012-08-17T13:41:35.537 回答
1

所有签入都应该有注释，但它不应该真正模仿更改本身。注释应该是关于更改内容的快速一般注释，而不是更改实施的细节，正如您所说，可以在更改本身中找到。

于 2012-08-17T13:43:03.683 回答