程序員的你，真的會寫 commit 信息嗎？
- 2020 年 3 月 12 日
- 筆記
作為一名優秀的程序員，作為一個優秀的團隊，作為一家優秀的軟件公司，不可能不用版本控制工具。
那麼請問，你覺得你填寫 commit 信息之後，過一周、一個月、一季度甚至是一年之後，你還能看得懂當初做過的提交嗎？當一個新同事來修改bug，請教你為什麼會這麼修復的時候，你腦海里是否還能浮現當初深思的場景呢？
我在前公司工作那幾年，代碼提交信息都是有嚴格要求，有統一的格式。在提交代碼之前，會通過另一位同事的協作（即 code review），審查你修復的大致內容，然後填上相應的修改信息才能入庫。
這樣的好處是什麼呢？就是能在下一個bug出來之後，很好地往回追溯，以確認是你修改引入，還是考慮不全，還是修改無效等。
這樣能更好地提高你寫代碼的能力，當你敲下鍵盤的時候，能考慮更多，能想得更多，更嚴謹。而且，還能在復盤的時候，有依可循，你覺得呢？
在那裡3年的時光，讓我養成了提交詳細信息的習慣。所以，當今天看到這篇外文，我饒有興趣地點進去閱讀，想知道歪果仁是如何做好一個優秀的 commit 信息，讀完之後，相信你也能收穫更多。
先來看看我做的原文翻譯：
停止編寫糟糕的提交信息
開始遵循Git提交信息的最佳實踐
作者：Devin Soni
時間：1月8日
我們都見過…
你正在開發一個項目，用到了Git版本控制工具。
你剛完成了一個代碼修改，希望快速地更新到你所在的分支。
這時候，你打開終端，快速敲了幾個命令，就可以把你更新的信息更新到遠程分支。
用到的命令如下：
gid add git commit -m "added new feature" git push
但是，當你做了一些測試，結果發現你的代碼中還存在一個bug。不用擔心–你很快就解決它，並且又做了一次提交去修復這個bug。
git add git commit -m "fix bug" git push
當你重複這個過程好幾次，就會得到一個提交日誌，如下所示：
此時，這對你來說似乎挺好的。
畢竟，你持續在做，而且你可以輕鬆地解釋你在做什麼–即使信息沒有很清楚地傳達。
這個問題
幾個月過去了，現在，另一個開發人員正在看你所做的更改。
他們試圖去裂解更改的高級細節，但是由於提交的描述信息有限，他們無法收集任何信息。
然後，他們去閱讀每個提交的差異信息。然而，即使這樣做了，他們仍然不能識別出你在實現中當時做的思考過程。
現在，由於軟件工程是一個協作過程，而且存在git blame操作，所以他們會找出是誰做了修改，並開始向你諮詢關於你的實現問題。
然後，因為時間過去很久，你也記不了多少信息。你通過提交記錄查看，但是也還是記不得在項目中實現這個修復背後的思想邏輯。
你給你同事發了一個很遺憾的表情，很遺憾的告訴他們，除了他們看到的提交信息，你也不能提供更多有效的信息了。
編寫良好的提交信息
希望上面講的實際情況，能很好的說明為什麼編寫良好的、信息豐富的git提交信息很重要。
在一個像軟件工程一樣需要協作的領域，我們必須使合作者很容易地在我們的工作中快速獲取到相應的上下文聯想信息。
在理想情況下，一個優秀的提交信息應該由三部分組成–主題、正文和結束行。
主題
主題應該單獨成行，寫上你提交記錄的概要信息。
他應該是祈使句，以大寫字母開頭，不用句號結尾，字數不能超過50個字符。（這是英文要求，我們中文提交可以做參考，甚至也用英文來寫提交信息）
一個好的主題可以完成This commit will…這樣的理解（同理，中文就是：這個提交將…：）
一個優秀的提交信息，比如「add new neural netword model to back-end」,(中文：向後端添加新的神經網絡模型)，這樣就很好地完成了這個句子
一個糟糕的提交信息，例如「fix bug」（你中招了嗎？）這個就不能很好的完成句子，從而產生「This commit will fix bug」(這個提交將修復bug)，這樣尷尬的字面理解。
內容
正文包含消息的主要內容，你可以在其中詳細描述有關更改的信息。也請注意，對弈一些非常小的提交，比如修復一個輸入錯誤，你可能不需要正文，因為主題已經提供了足夠的信息。
在正文中，你應該更詳細地介紹你所做的修改，並解釋你所做修改的上下文內容。
你可以解釋為什麼要進行這些修改，為什麼要選擇以這種方式實現這些修改，以及其他任何能幫助別人理解你思考過程的內容。
盡量不要重複那些從diff中的代碼修改中可以很明顯理解的內容，沒有必要逐行解釋你的修改。更多的關注更高層次的細節，這些細節可能在閱讀代碼時並不明顯。我們的最終目的是為圍繞這個變更的開發過程提供上下文信息，主要是關注其動機和目標。
結束行
最後，結束行是提交信息的最後一行。
這裡可以放置關於提交的有用的元數據，比如 JIRA單號、GitHub issue號，作者姓名，以及其他鏈接等。這有助於將你修改相關的重要信息鏈接在一起。（我個人的習慣，加上日期）。
結語
很高興你和我一起學習完了，請問此時的你什麼感想？這裡遇到的問題，你是否曾經遇到過。
如果是，說明你還有很大的提升空間，你修改bug，回溯問題的效率還能更高；如果你已經在做了，那麼恭喜你，請繼續保持。
作為程序員，基本上每天都在用版本控制工具，編寫良好的 commit 日誌是對自己負責，也是對項目負責，能讓你事半功倍，實踐起來！
作者簡介：躍哥，前菊廠Android攻城獅，現遊戲公司Java主程，奔跑中的技術人！
