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

Git Log 之痛

在《The Art of Readable Code》這本經(jīng)典書中，有個形象的比喻介评，衡量代碼可讀性的指標是閱讀代碼時每分鐘的 WTF 次數(shù)库北，而在讀 Git 提交歷史的時候，不知道你有多少次爆粗口们陆？不相信寒瓦？你現(xiàn)在打開公司演進最快的項目，執(zhí)行 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 方法去記錄乾颁，你后來翻看的時候也不會錯過細節(jié)涂乌。

回到正題，Git Log 本質(zhì)上不也是事件日志么英岭？必然是線上出了問題湾盒、產(chǎn)品提出了需求、工程師自己做了重構或技術改進才會導致它的變遷诅妹。如果沒有詳盡記錄每次變遷的細節(jié)罚勾，代碼 Review 的人怎么知道你做了什么？上線后遇到問題怎么去追溯吭狡？新人接手代碼怎么去理解尖殃？

解決問題

因為 Git 的特殊性，Git 內(nèi)核已經(jīng)能把 5W1H 里面的 who划煮、when 作為 commit 元信息記錄下來送丰，而研發(fā)活動的 where 明顯是不需要記錄的，真正需要工程師關注的是 what弛秋、why器躏、how，這 3 項重要信息的載體就是 commit message铐懊。相信讀到這里邀桑，你已經(jīng)明白我想說什么了。

下面提出一種可以幫你寫出高可讀 commit message 的實踐方法科乎，這個方法并非原創(chuàng)壁畸，最早的實踐來自于這篇文章。簡單來說就是要在 commit message 中記錄本次提交的 what茅茂、why捏萍、how，那么怎么把這個想法集成到你的開發(fā)工作流里面呢空闲？可以參考下面的步驟來完成：

1. 設置 .gitmessage 模板

這是 Git 內(nèi)置就支持的令杈，你可以為每次提交的 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

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

如同阿米爾汗在給他女兒做摔跤戰(zhàn)術指導時說的話：拿五分很難，但不是沒有可能担平。習慣的養(yǎng)成定不容易示绊，但是是可行的锭部，如果你認識到這點，離習慣養(yǎng)成已經(jīng)很近了面褐。

4. 給用 Vim 的同學

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

autocmd Filetype gitcommit setlocal spell textwidth=80

5. 最重要的是內(nèi)容

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

• What: 簡短的描述這次的改動
• Why：為什么修改？就是要說明這次改動的必要性摄杂，可以是需求來源坝咐，任務卡的鏈接，或者其他相關的資料析恢；
• How: 做了什么修改墨坚？需要說明的是使用了什么方法（比如數(shù)據(jù)結構、算法）來解決了哪個問題映挂；

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

從本質(zhì)上來說亏拉，上面只是你思考問題的框架和記錄內(nèi)容的形式，真正重要的是你要仔細思考的那幾個問題逆巍，因為一定程度上及塘，commit message 就是文檔，活的文檔锐极，記錄了倉庫的所有變遷笙僚。

總結

怎么讓你的代碼可以追溯也是優(yōu)秀工程師必備的素質(zhì)，相信讀到這里灵再，你對如何寫出高可讀的 commit message 的原因肋层、好處、方法有了清晰的認識翎迁，紙上得來終覺淺栋猖，絕知此事要躬行，接下來你就需要把這種方法運用到實際工作中鸳兽，相信我，你的同事發(fā)現(xiàn)之后會開始感激你罕拂、效仿你揍异。

One More Thing

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