【译】求你不要再写没用的提交信息了

开始尝试优化你的 Git 提交信息吧



我们都看到过的



你在一个项目中使用 Git 作为版本控制。



当你做完了一次修改之后，你想要尽快更新你的分支。



所以你打开了终端，输入了下面这些命令，完成了一次远端分支的更新。



git add .
git commit -m "added new feature"
git push



然后你做了一些自测，发现了一个新鲜的 bug。问题不大，你很轻松的就解决掉了这个 bug，现在你需要把新的代码再次提交到远程分支，于是你很熟练的使用起 Git 命令。



git add .
git commit -m "fix bug"
git push



你几乎每天都在重复做着这样的事情，当你打开 Git log 时，你会发现它长成了这个样子。





到目前为止，一切看上去对你来说都还不错。毕竟你很熟悉你的代码仓库，即使不需要提交信息的提醒，你也知道每次修改都是在进行了哪些操作。



存在的问题



过了几个月，其他的开发者浏览了你过去的修改，他们想要尝试更深入的理解关于你所做的修改的一些细节问题，但是你的提交信息并不具备描述性，他们也就无法从中获取任何有用的信息。



无奈之下，他们只能挨个查看每次提交的不同，然而即使这么做了，他们也还是不能很明确的知道你在开发过程中一些选择的理由和你的一些思考。



由于软件开发是一个协作的过程中，所以人们总是会使用 `` git blame `` 操作来查看是谁对代码做了修改，并且会问你一些关于代码的问题。但是距离你写这段代码已经过去很长时间了，你的印象也比较模糊。当你查看你的提交时，你发现自己很难说出当时为什么要这么写，以及其中的一些逻辑细节。



你给同事发送了一个悲伤的表情，并且告诉他们，你没有办法给他们提供更多的信息。



书写优秀的提交信息



希望通过上面的故事，你已经知道了为什么要编写良好的、信息丰富的 Git 提交信息：



在软件工程这样需要协作的领域中，它可以帮助我们快速理解上下文。理想情况下，Git 提交信息需要由三部分组成：主题、正文和结语。



主题



主题需要是一句话来概括你提交内容所涉及的修改。它需要是祈使时态，以大写字母开头，结尾没有句号，并且最好小于50个字。



一个好的主题格式应该是像“This commit will …”这样的。好的提交信息也应该是一个比较完整的句子。“add new neural network model to back-end”。



而不好的提交信息就不是一个完整描述的句子，比如最常见的“fix bug”。



正文



正文需要包含你要传达的信息，让其他人在其中能够了解更多关于这次修改的细节。对于一些比较修改的修改，比如改动了一个变量类型，你可能不需要写正文，主题就足够描述这次修改的内容了。



在正文中，你应该更详细的描述这次修改中的一些细节问题，并且解释你所做的事情的前因后果。



你可以解释为什么要做出这个修改，为什么用这种特殊的方式来实现，或者其他你觉得能够帮助其他人理解你的修改过程的信息。



注意不要重复描述代码中显而易见的逻辑，正文也不是让你一行一行的解释代码，大家更加关注的是代码中不容易看出来的更深层的一些细节问题。我们的最终目标是为这次的修改提供有效的上下文信息，即更改主要的动机和目标。



结束语



最后，结束语应该出现在你的提交信息的最后一行。



你可以在这里提供一些关于此次修改的元数据，比如 JIRA 号，GitHub issue 号，合作者姓名，和附加信息的链接。



这有助于将你的修改的相关重要信息链接在一起。



原文链接



https://medium.com/better-programming/stop-writing-bad-commit-messages-8df79517177d