摘要：共字，讀完需分鐘。下面提出一種可以幫你寫出高可讀的實(shí)踐方法，這個(gè)方法并非原創(chuàng)，最早的實(shí)踐來(lái)自于這篇文章。本文作者王仕軍，商業(yè)轉(zhuǎn)載請(qǐng)聯(lián)系作者獲得授權(quán)，非商業(yè)轉(zhuǎn)載請(qǐng)注明出處。

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

在《The Art of Readable Code》這本經(jīng)典書中，有個(gè)形象的比喻，衡量代碼可讀性的指標(biāo)是閱讀代碼時(shí)每分鐘的 WTF 次數(shù)，而在讀 Git 提交歷史的時(shí)候，不知道你有多少次爆粗口？不相信？你現(xiàn)在打開公司演進(jìn)最快的項(xiàng)目，執(zhí)行 git log，信息量過(guò)少甚至是誤導(dǎo)的 commit message 非常常見，比如：

fix     => 這到底是 fix 什么？為什么 fix？怎么 fix 的？
update  => 更新了什么？是為了解決什么問(wèn)題？
test    => 這個(gè)最讓人崩潰，難道是為了測(cè)試？至于為了測(cè)試而去提交一次代碼么？

說(shuō)不定，你在這種 commit message 中也貢獻(xiàn)了一份力量呢。

我們先放下 Git 提交日志來(lái)看看典型的后端日志記錄，如下面這則 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 包含了哪些要素呢？

用戶請(qǐng)求的時(shí)間（time）；

用戶請(qǐng)求的地址（request）、從何而來(lái)（refer）；

用戶來(lái)源（remote_addr）；

服務(wù)端響應(yīng)（status, byte, elapsed）；

...

回憶下小學(xué)的知識(shí)，如何準(zhǔn)確的描述一次事件？對(duì)，就是 5W1H 法則，具體說(shuō)就是誰(shuí)（who）在什么時(shí)候（when）、什么地點(diǎn)（where）因?yàn)槭裁矗╳hy）而做了什么事情（what），他是怎么做的（how），access log 是典型的事件日志，所以 access log 的記錄完全可以參照 5W1H 方法去記錄，你后來(lái)翻看的時(shí)候也不會(huì)錯(cuò)過(guò)細(xì)節(jié)。

回到正題，Git Log 本質(zhì)上不也是事件日志么？必然是線上出了問(wèn)題、產(chǎn)品提出了需求、工程師自己做了重構(gòu)或技術(shù)改進(jìn)才會(huì)導(dǎo)致它的變遷。如果沒(méi)有詳盡記錄每次變遷的細(xì)節(jié)，代碼 Review 的人怎么知道你做了什么？上線后遇到問(wèn)題怎么去追溯？新人接手代碼怎么去理解？

因?yàn)?Git 的特殊性，Git 內(nèi)核已經(jīng)能把 5W1H 里面的 who、when 作為 commit 元信息記錄下來(lái)，而研發(fā)活動(dòng)的 where 明顯是不需要記錄的，真正需要工程師關(guān)注的是 what、why、how，這 3 項(xiàng)重要信息的載體就是 commit message。相信讀到這里，你已經(jīng)明白我想說(shuō)什么了。

下面提出一種可以幫你寫出高可讀 commit message 的實(shí)踐方法，這個(gè)方法并非原創(chuàng)，最早的實(shí)踐來(lái)自于這篇文章。簡(jiǎn)單來(lái)說(shuō)就是要在 commit message 中記錄本次提交的 what、why、how，那么怎么把這個(gè)想法集成到你的開發(fā)工作流里面呢？可以參考下面的步驟來(lái)完成：

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

What: 簡(jiǎn)短的描述干了什么

Why:

* 我為什么要這么做？

How:

* 我是怎么做的？這么做會(huì)有什么副作用？

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

[commit]
  template = ~/.gitmessage

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

git commit -m ""

因?yàn)檫@種提交方式是不會(huì)彈出模板來(lái)讓你填寫的，你提交的命令應(yīng)該改成：

git commit

具體的操作過(guò)程見下面的動(dòng)圖：

如同阿米爾汗在給他女兒做摔跤戰(zhàn)術(shù)指導(dǎo)時(shí)說(shuō)的話：拿五分很難，但不是沒(méi)有可能。習(xí)慣的養(yǎng)成定不容易，但是是可行的，如果你認(rèn)識(shí)到這點(diǎn)，離習(xí)慣養(yǎng)成已經(jīng)很近了。

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

autocmd Filetype gitcommit setlocal spell textwidth=80

寫出高可讀的 commit message 需要你對(duì)每次提交的改動(dòng)做認(rèn)真深入的思考，認(rèn)真回答上面提到的幾個(gè)問(wèn)題：

What: 簡(jiǎn)短的描述這次的改動(dòng)

Why：為什么修改？就是要說(shuō)明這次改動(dòng)的必要性，可以是需求來(lái)源，任務(wù)卡的鏈接，或者其他相關(guān)的資料；

How: 做了什么修改？需要說(shuō)明的是使用了什么方法（比如數(shù)據(jù)結(jié)構(gòu)、算法）來(lái)解決了哪個(gè)問(wèn)題；

此外，還有個(gè)非常重要的點(diǎn)就是本次修改的副作用可能有什么，因?yàn)楣こ叹褪遣粩嘣谧鰴?quán)衡，本次修改為以后留下了什么坑？還需要什么工作？都可以記錄在 commit message 中。

從本質(zhì)上來(lái)說(shuō)，上面只是你思考問(wèn)題的框架和記錄內(nèi)容的形式，真正重要的是你要仔細(xì)思考的那幾個(gè)問(wèn)題，因?yàn)橐欢ǔ潭壬希?b>commit message 就是文檔，活的文檔，記錄了倉(cāng)庫(kù)的所有變遷。

怎么讓你的代碼可以追溯也是優(yōu)秀工程師必備的素質(zhì)，相信讀到這里，你對(duì)如何寫出高可讀的 commit message 的原因、好處、方法有了清晰的認(rèn)識(shí)，紙上得來(lái)終覺(jué)淺，絕知此事要躬行，接下來(lái)你就需要把這種方法運(yùn)用到實(shí)際工作中，相信我，你的同事發(fā)現(xiàn)之后會(huì)開始感激你、效仿你。

本文作者王仕軍，商業(yè)轉(zhuǎn)載請(qǐng)聯(lián)系作者獲得授權(quán)，非商業(yè)轉(zhuǎn)載請(qǐng)注明出處。如果你覺(jué)得本文對(duì)你有幫助，請(qǐng)點(diǎn)贊！如果對(duì)文中的內(nèi)容有任何疑問(wèn)，歡迎留言討論。想知道我接下來(lái)會(huì)寫些什么？歡迎訂閱我的掘金專欄或知乎專欄：《前端周刊：讓你在前端領(lǐng)域跟上時(shí)代的腳步》。