我该如何说服我的开发人员加入WANT，以在源代码提交中添加注释？

我知道可以将Subversion（我们在工作中使用的东西）配置为要求对提交进行注释，但是我无法简单地将其打开。我知道我对提交进行评论的原因是因为它（即使只是作为慢跑者）对于快速了解提交背后的原因很有用。但是，这似乎还不足以与我经常得到的两个回答作斗争：

1. 它花费的时间太长，我只想将我的更改放入存储库中。
2. 只需看一下差异就很容易了。

我什至向他们展示了简单地输入JIRA问题ID以及它如何自动与问题联系在一起的价值，但仍然与他们无关。

最糟糕的是，可以拨打电话的人在同一个阵营中：不想打扰，并且可以看差异。

我知道这是正确的做法，但是如何让他们看到光线呢？即使我无法说服我的开发人员，我又如何说服管理层这对企业是正确的呢？

专注于“为什么”。很好地查看了差异，看到有人更改了代码段或类似内容的逻辑流程，但是为什么他们要更改它呢？原因通常在关联的票证中（您的JIRA）。

他们可能想知道“为什么”为什么很重要，但是在两年内当您发现某个影响该更改的错误时，知道为什么这样做对不仅修复您的新错误，而且确保您不会导致旧错误重新出现。

还有审计原因。绑定提交和票证ID可以很容易地说出来，我们推出了版本2，它修复了缺陷23、25、26和27，但是没有针对缺陷24的提交，因此它仍然很突出。

让他们进行合并并处理支持。再一次，也许您无权执行此操作，但是如果您发现自己是以前一次提交中解决问题的人，则有礼貌地将其发送给篱笆并说出来。我无法告知您所做的事情，因为没有提交注释，您进行了这些更改需要弄清楚。

也用于合并分支。不知道这是否取决于您，但这是我发现评论有用的一个方面。

再说一次，不是在你的船上，而是当我管理一个软件团队时，我告诉他们，如果他们做出了很好的提交评论，我会用这些代替每周状态报告。在那之后获得了出色的承诺，对我来说，更容易跟踪经理的情况。

出于相同的原因，我们需要签入注释，因为我们在代码中需要换行和间隔。为了使事情更容易追踪，请理解阅读和理解。

有时您需要进行比较，但通常不需要。强迫开发人员进行比较时，他们所需要的只是阅读2-3个句子，这完全是浪费时间。我想知道为什么他们看不到开发人员时间的价值。

• 树立一个好榜样。使自己的提交消息成为有用的闪亮示例。包括对您的团队用于管理故事和缺陷的任何其他系统的引用。简短地总结一下更改，并很好地解释为什么必须进行更改，而不是在每次提交时都进行其他更改。
• 每当缺少像样的提交消息导致您需要额外的工作时，请向提交者提问。坚持这一点（但不要混蛋）。
• 如果没有超越您的角色，请编写一个脚本，使用提交消息发送每日变更日志。这将使您的论点更具可信度，即有用的消息比浏览修订更有用。这也可能会帮助您管理，因为他们会每天看到发生的事情。
• 确定您的盟友。希望至少还有一个人与您达成协议（也许默默不同意）。找到那个人或那些人，并进一步说服他们，以免您一个人呆着。
• 当有机会提及体面的提交消息如何节省您的时间（或不良消息浪费您的时间）时，请抓住机会。

不要害怕成为吱吱作响的轮子。与其他人的不良习惯作斗争通常是一场消耗战。

这一定是我所听到的最奇怪的问题之一。人们花费数小时甚至数天的时间来修复某些问题，而花费额外的2秒时间输入提交消息是否太长？我不得不说我会担心与这样近视的人一起工作。他们显然没有利用自己的工具来发挥全部潜力。

这是我上周参与的代码审查的一个示例。我们的版本控制软件不会保留合并的历史记录，因此，对于较旧的更改，您必须找到进行合并的确切分支，否则提交消息仅显示诸如“从分支Y合并”之类的内容。分支Y可能显示为“从分支Z合并”，而分支的更深层嵌套实际上具有真正的提交消息。

新员工不知道如何正确追踪历史记录，这意味着他实际上只是在处理差异。他看到一些注释掉的代码与他正在跟踪的错误有关。当他取消注释代码时，他的错误消失了。他假设有人在调试期间注释掉了代码，然后错误地将其签入。

在代码审查期间，这对我们中的几个人来说并不对，所以我追踪了真正的提交消息，发现一年前有删除该代码的正当理由。新员工能够修复其代码以修复新发现的错误，而无需重新引入旧错误。

有更好的方法来避免引入那种类型的回归，例如彻底的单元测试，但是以某种方式，我看不到那些不愿意花2秒的提交消息“浪费”时间进行单元测试的人。

我在这里遇到了完全相同的问题，因此我向Subversion 添加了一个预提交钩子，因此它不接受任何以用户故事编号（某些基本模式与所需格式匹配）开头的提交。

没有阻止他们进入000-0000的方法，但是只有当一个破坏性的白痴在他们有一个完全可以接受的数字时才组成一个数字。

我花了几天的时间才尝试这样做，以查找进入了哪些构建的用户故事。是的，它是在其他地方处理过程失败的方法，但是它仍然是令人难以置信的有价值的信息。

好的提交评论就像任何好的文档一样，是您大脑慢和已不复存在的缓存，或者是任何冗长的调试/问题分析/调查结果的缓存。

例如，每当您花时间找出一些问题，例如调试，分析日志或其他内容时，发现和结果都是宝贵的。当然，大多数任务可以重复，但是可能需要一些时间。因此，您应该始终记录结果。

尽管如此，文档编制仍然需要时间，有时甚至感觉没有必要，例如“我们只需要这样做一次，为什么要写下来”。没关系，但是由于您第一次没有记录结果，因此第二次执行相同的操作时，记录结果当然很聪明。

因此，如果您的同事觉得添加提交评论的工作量很大，例如至少要指出他们正在解决的Jira案例/票证，那么他们可能会受到不断回答有关每个原因的问题的压力的激励变更集。

我认为，应根据所要求的信息来编制文件。例如，邮件通信是一个很好的文档系统。问题收到的答案可以稍后检索，这就是邮件列表和论坛在实践中作为知识库的工作方式。

不幸的是，在我工作的地方，邮件会在3个月后自动删除，因此实际上并不总是能正常工作。

寻求宽恕，而不是允许。

虽然苛刻，但我只是这样做。在支持者和反对者之间，我的分配比例为50/50，大多数人与小组成员的水平相同。这些论点是“我不能打扰”和“这有什么意义？”。（两者都表示冷漠和懒惰，不是真正的担忧）。

我添加了pre-commit钩子，该钩子简单地测量了字符串的长度，并在拒绝之前给出了一些幽默的信息。我在邮件中输入了我的名字，因此对“这种愤怒”的责任很明确。当然，“反对派”可以轻松地将其删除，但是深入研究脚本比添加一个注释要花费更多的精力！

在一周的时间里，我收到了诸如* *（删除已删除）或kjhfkwhkfjhw之类的消息。之后，基本消息开始出现。

一年过去了，怀疑论者使用了有意义的评论，并实际上承认他们的目光短浅。我永远无法达成共识，但我当然可以宽恕别人，甚至可以赢得信誉。它有效，人们使用它。

如果您想变得更友善（或觉得自己会遇到麻烦），请请求允许添加试用期的提交钩子。假设如果人们在2周或4周内不喜欢它，您将把它拿出来。他们很可能会失去兴趣...或者变得喜欢它。

我通常通过以下方式说服人们：

• 具有充分支持理由的辩证法
• 以身作则
• 损耗

如果我想让我们的团队做得足够糟糕，我会一直困扰着我，直到我明白了。在那些可以指出可以节省时间/金钱的时间里，如果我一直在做X，我会尽量避免。

提交评论的其他良好理由：

• 从注释自动生成ChangeLog。
• 审计跟踪，以查找错误修复和功能补充。这在团队内部和外部都非常有用。
• 使提交邮件更有用。
• 阻止我询问开发人员X所做的工作（几乎在每次提交之后）。

• 检查您的SVN日志，了解6个月前所做的模糊处理。
• 询问有关此事的一些问题，而无需告知完成的时间
• ???
• 利润

您如何使他们想要添加好的评论？

从与一位同事的经历中我刚刚得到了。在项目结束时，我们必须编写一个总结文档，说明整个项目中所做的所有更改。没有做出好的提交记录，我的同事发现此任务非常耗时，现在改用每次提交进行冗长的注释。

因此，一种解决方法是让开发人员在项目结束时编写摘要文档，其中详细说明了对哪些文件进行了哪些更改，添加/删除了哪些文件以及原因。

向闭门造车的管理人员提出以下建议：

最坏的情况发生了：所有高级开发人员都走了出去。

随着公司争相填补空白的开发人员席位，管理团队的任务是将系统状态传达给客户。

问他们，他们认为在重构应用程序的历史上将使他们的工作更轻松的是什么：

阅读通俗易懂的英语文章可以清楚地描述系统的变化状态？

还是他们更愿意看代码差异并自己解决？

我想说服他们的一种方法是实际体验您所感受到的痛苦。

例如，假设他们正在解决以下问题：他们有一个错误，当针对同一代码实施另一个错误修复（反讽）时，就会以某种方式出现。能够仅通过搜索提交消息来查找它（这会发现是谁编写的）是很棒的。

另一种方法是向他们解释，提交消息可能有助于暗示为什么以某种方式实现某些东西。即使提交消息只是说“功能X”，您仍然可以获得执行它的线索，因此您知道可以与谁交谈。

但是，这似乎还不足以与我经常得到的两个回答作斗争：

1. 它花费的时间太长，我只想将我的更改放入存储库中。
2. 只需看一下差异就很容易了。

您是否尝试过向其他开发人员提出挑战，以便他们通过发表评论获得其他好处？可以从几个不同的角度来看这个：

1. 加强他们的游戏-这可能是一个比较棘手的观点，但是这里的想法是，他们会花一些时间并习惯这个想法，这样习惯是花更长的时间才能走另一条路。这里的另一点是，评论将受到多少审查？如果您想在评论中写一个简短的故事，我可以理解他们的观点。
2. 补贴变更-这是您进行某种竞赛的一种方式，可以通过最初的买入尝试这种方式，也可以通过其他方式鼓励进行一段时间的变更。

还需要考虑的另一件事是，您是否知道您的其他开发人员正在管理您的工作场所？如果他们试图昨天完成10件事，那么我可以理解，他们可能不想更改他们认为已经有效的东西。您是否要告诉他们，“不，这不起作用？” 如果是这样，那么我可以看到他们在这一点上可能会有些防御或好斗。如果您试图告诉他们，“虽然这可能行得通，但有另一种可能会更好……”，那么您可能会有机会。IMO，在这里拥有“比你更神圣”的态度不会帮助您。

看待这个另一种方式是作为参与种植自己的职业生涯开发（S）的方式-他们应该拥有的文档他们的工作。

除了上面引用的文章中提出的其他要点外，还能够查看代码更改以找出更改的位置/时间/原因。当追踪一个难以捉摸的错误时，这可能至关重要。

在使他们确信对提交进行注释很重要之后，可以创建一个脚本来强制对提交进行注释，否则它将失败。您甚至可以指定最少的字符以确保其有意义的注释。这将帮助他们“记住”。

但是，重要的是，他们必须理解@Kevin所说的“为什么”，否则他们将只添加随机注释。

你有代码审查吗？可能有帮助的一件事是制定一个规则，即任何提交或合并都必须由另一位开发人员查看并批准。然后，如果您是审阅者，则必须要求进行提交的开发人员向您解释他做了什么。一旦他做完，您应该让他在评论中输入他刚刚告诉您的内容。通常，当人们无法连贯地解释所做的更改时，这意味着这些更改不应该首先进行。

不过，我不得不说，人们如何才能反对那些与提交评论一样有用的东西？根本不会花很长时间，而且这是一个值得花费的时间。撰写评论会迫使您考虑一下刚刚完成的操作。它甚至可能导致您查看差异以确保您确实完成了您认为已完成的工作，并且没有做任何愚蠢的事情。

当您不写评论时，您便显得草率而不受纪律。而且，如果您坚持不要求您撰写评论，则表示您故意过失。

告诉他们这是保持机会的50,000行方法混乱的唯一方法，然后考虑在将来编写更好，更明确的代码，这样您就不必处理一堆毫无意义的注释，而这些注释会使您的代码库膨胀。

这是一个过程更改项：让经理将由“ x”开发的代码分配给“ Y”，以便仅对代码进行质量保证检查，包括评论的质量检查。

在我自己的组织中，开发人员不允许执行自己代码的最终质量检查并检入，这必须由另一位开发人员完成。质量检查的一部分是评论，因此没有评论，也没有签入。我们做很多合同工作，而我们的“艺术”实际上是他人的合同知识产权，因此其他人需要能够理解和利用我们的代码。另外，有时候项目经过漫长的休假之后又回到我们的手中，我们需要能够在18-24个月后拿起代码，并了解为什么，在何处以及如何到达我们面前的代码工件。这提供了编写提交评论的自我服务动机。

要求并让您的其他开发人员进行一些合并，并查找历史记录并比较历史记录中的一些文件。

很有可能第二天他们会要求您发表评论。

这里有一些建议：

1. 不要试图改变世界。你会失败的。
2. 相反，您应该意识到每个人的工作方式略有不同。没有人适合所有人。
3. 在人们的工作过程中需要一些特定的步骤是非常邪恶的。更改这些过程需要10年。您要他们在下一个截止日期之前这样做。
4. 即使简单的过程更改也可能需要很长时间。
5. 关于提交的一些小评论太微不足道了，无法更改这些过程。
6. 您可以假定他们做得很好，但是应该给他们足够的自由来选择步骤。有经验的开发人员可能不需要采取一些繁琐的步骤。
7. 如果您要照顾新手，则可能需要更强大的流程，但是经验丰富的开发人员不应对胡扯。
8. 对必须完成的工作施加严格的限制永远不会起作用，它只会使人放慢速度（如果他们太快可能会很好）
9. 许多人认为自己的方式是做事的唯一正确方法。希望你不是其中之一。

如果您的源代码管理提供了证明，请打开强制注释以防止任何未注释的命令。非常简单，每个人都将很快意识到键入评论只需5秒钟。

但是，未注释的提交是最小的否定之一。我参与了许多成功的项目，没有评论任何提交。不要把你的内裤弄得一团糟。