使用 "5W1H" 寫出高可讀的 Git Commit Message

共 1926 字，讀完需 4 分鐘。全部工程師都知道，代碼是編寫一次，修改不少次，而後閱讀更屢次，代碼可讀性的重要程度不言而喻，可是在項目演進過程當中有個很重要的記錄也是會讀不少次的，那就是 Git 的提交日誌，而提交日誌裏面信息量最大的應該是 commit message，本文靈感來自 Linux 做者 Linus Torvalds 在 GitHub 上對 commit mesage 的吐槽。

Git Log 之痛

在《The Art of Readable Code》這本經典書中，有個形象的比喻，衡量代碼可讀性的指標是閱讀代碼時每分鐘的 WTF 次數，而在讀 Git 提交歷史的時候，不知道你有多少次爆粗口？不相信？你如今打開公司演進最快的項目，執行 git log，信息量過少甚至是誤導的 commit message 很是常見，好比：

fix     => 這究竟是 fix 什麼？爲何 fix？怎麼 fix 的？
update  => 更新了什麼？是爲了解決什麼問題？
test    => 這個最讓人崩潰，難道是爲了測試？至於爲了測試而去提交一次代碼麼？複製代碼

說不定，你在這種 commit message 中也貢獻了一份力量呢。

正視問題

咱們先放下 Git 提交日誌來看看典型的後端日誌記錄，以下面這則 access log：

remote_addr=[127.0.0.1] http_x_forward=[-] time=[19/Apr/2017:07:28:13 +0800] request=[GET /admin/edu/exam_scores/index/225 HTTP/1.1] status=[200] byte=[15745] elapsed=[0.309] refer=[http://stu.youcaiedu.com/admin/edu/contests] body=[-] ua=[Mozilla/5.0 （Macintosh; Intel Mac OS X 10_12_4） AppleWebKit/537.36 （KHTML, like Gecko） Chrome/57.0.2987.133 Safari/537.36] cookie=[JSESSIONID=aaaXlJyT6Ju-K-FbLuWPv; pgv_pvi=7986424832; pgv_si=s905561088; easycms=a16pbumhusksq3vpcogcv2n715; toolbarDisplay=hide; _ga=GA1.2.1604145244.1486802034] gzip=[7.71]複製代碼

好的 access log 包含了哪些要素呢？

• 用戶請求的時間（time）；
• 用戶請求的地址（request）、從何而來（refer）；
• 用戶來源（remote_addr）；
• 服務端響應（status, byte, elapsed）；
• ...

回憶下小學的知識，如何準確的描述一次事件？對，就是 5W1H 法則，具體說就是誰（who）在何時（when）、什麼地點（where）由於什麼（why）而作了什麼事情（what），他是怎麼作的（how），access log 是典型的事件日誌，因此 access log 的記錄徹底能夠參照 5W1H 方法去記錄，你後來翻看的時候也不會錯過細節。

回到正題，Git Log 本質上不也是事件日誌麼？必然是線上出了問題、產品提出了需求、工程師本身作了重構或技術改進纔會致使它的變遷。若是沒有詳盡記錄每次變遷的細節，代碼 Review 的人怎麼知道你作了什麼？上線後遇到問題怎麼去追溯？新人接手代碼怎麼去理解？

解決問題

由於 Git 的特殊性，Git 內核已經能把 5W1H 裏面的 who、when 做爲 commit 元信息記錄下來，而研發活動的 where 明顯是不須要記錄的，真正須要工程師關注的是 what、why、how，這 3 項重要信息的載體就是 commit message。相信讀到這裏，你已經明白我想說什麼了。

下面提出一種能夠幫你寫出高可讀 commit message 的實踐方法，這個方法並不是原創，最先的實踐來自於這篇文章。簡單來講就是要在 commit message 中記錄本次提交的 what、why、how，那麼怎麼把這個想法集成到你的開發工做流裏面呢？能夠參考下面的步驟來完成：

1. 設置 .gitmessage 模板

這是 Git 內置就支持的，你能夠爲每次提交的 commit message 設置一個模板，每次提交的時候都能促使你遵循這個思考的模式去編寫 commit message，好比下面是個人模板，存放在 ~/.gitmessage：

What: 簡短的描述幹了什麼

Why:

* 我爲何要這麼作？

How:

* 我是怎麼作的？這麼作會有什麼反作用？複製代碼

2. 讓模板生效

在全局 Git 配置 ~/.gitconfig 中添加以下配置：

[commit]
  template = ~/.gitmessage複製代碼

3. 擁抱新模板

配置好模板以後，你要放棄在提交時直接指定 commit message 的習慣作法，即下面這種提交方式：

git commit -m "<commit message here>"複製代碼

由於這種提交方式是不會彈出模板來讓你填寫的，你提交的命令應該改爲：

git commit複製代碼

具體的操做過程見下面的動圖：

如同阿米爾汗在給他女兒作摔跤戰術指導時說的話：拿五分很難，但不是沒有可能。習慣的養成定不容易，可是是可行的，若是你認識到這點，離習慣養成已經很近了。

4. 給用 Vim 的同窗

爲了更好的 commit message 閱讀者體驗，可能你須要考慮給 commit message 裏面的內容自動換行，讓內容控制在輕鬆能看到的寬度以內，使用 Vim 的同窗能夠在你的 ~/.vimrc 裏面增長下面的配置：

autocmd Filetype gitcommit setlocal spell textwidth=80複製代碼

5. 最重要的是內容

寫出高可讀的 commit message 須要你對每次提交的改動作認真深刻的思考，認真回答上面提到的幾個問題：

• What: 簡短的描述此次的改動
• Why：爲何修改？就是要說明此次改動的必要性，能夠是需求來源，任務卡的連接，或者其餘相關的資料；
• How: 作了什麼修改？須要說明的是使用了什麼方法（好比數據結構、算法）來解決了哪一個問題；

此外，還有個很是重要的點就是本次修改的反作用可能有什麼，由於工程就是不斷在作權衡，本次修改成之後留下了什麼坑？還須要什麼工做？均可以記錄在 commit message 中。

從本質上來講，上面只是你思考問題的框架和記錄內容的形式，真正重要的是你要仔細思考的那幾個問題，由於必定程度上，commit message 就是文檔，活的文檔，記錄了倉庫的全部變遷。

總結

怎麼讓你的代碼能夠追溯也是優秀工程師必備的素質，相信讀到這裏，你對如何寫出高可讀的 commit message 的緣由、好處、方法有了清晰的認識，紙上得來終覺淺，絕知此事要躬行，接下來你就須要把這種方法運用到實際工做中，相信我，你的同事發現以後會開始感激你、效仿你。

One More Thing

本文做者王仕軍，商業轉載請聯繫做者得到受權，非商業轉載請註明出處。若是你以爲本文對你有幫助，請點贊！若是對文中的內容有任何疑問，歡迎留言討論。想知道我接下來會寫些什麼？歡迎訂閱個人掘金專欄或知乎專欄：《前端週刊：讓你在前端領域跟上時代的腳步》。