摘要：共字，讀完需分鐘。下面提出一種可以幫你寫出高可讀的實踐方法，這個方法并非原創，最早的實踐來自于這篇文章。本文作者王仕軍，商業轉載請聯系作者獲得授權，非商業轉載請注明出處。

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

在《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，那么怎么把這個想法集成到你的開發工作流里面呢？可以參考下面的步驟來完成：

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

What: 簡短的描述干了什么

Why:

* 我為什么要這么做？

How:

* 我是怎么做的？這么做會有什么副作用？

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

[commit]
  template = ~/.gitmessage

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

git commit -m ""

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

git commit

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

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

為了更好的 commit message 閱讀者體驗，可能你需要考慮給 commit message 里面的內容自動換行，讓內容控制在輕松能看到的寬度之內，使用 Vim 的同學可以在你的 ~/.vimrc 里面增加下面的配置：

autocmd Filetype gitcommit setlocal spell textwidth=80

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

What: 簡短的描述這次的改動

Why：為什么修改？就是要說明這次改動的必要性，可以是需求來源，任務卡的鏈接，或者其他相關的資料；

How: 做了什么修改？需要說明的是使用了什么方法（比如數據結構、算法）來解決了哪個問題；

此外，還有個非常重要的點就是本次修改的副作用可能有什么，因為工程就是不斷在做權衡，本次修改為以后留下了什么坑？還需要什么工作？都可以記錄在 commit message 中。

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

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

本文作者王仕軍，商業轉載請聯系作者獲得授權，非商業轉載請注明出處。如果你覺得本文對你有幫助，請點贊！如果對文中的內容有任何疑問，歡迎留言討論。想知道我接下來會寫些什么？歡迎訂閱我的掘金專欄或知乎專欄：《前端周刊：讓你在前端領域跟上時代的腳步》。