【譯】求你不要再寫沒用的提交信息了

開始嘗試優化你的 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 號，合做者姓名，和附加信息的連接。

這有助於將你的修改的相關重要信息連接在一塊兒。

原文連接

medium.com/better-prog…