思考:如果讓你制定程式碼提交規範(Git工具),你會怎麼做?
被忽略的細節
程式碼的提交資訊是開發中一個很小的細節,由於它本身對程式碼執行本身不造成任何影響,主要作用在於方便查詢、回退程式碼,所以很容易被開發者忽略。 但是它的意義就像專案文件、註釋一樣,是高質量專案必備的內容,好的提交資訊不僅能幫助開發者快速找到指定版本的程式碼,同時節體現的也是開發者的習慣和意識。
這篇文章想和大家聊聊這個小小的細節和軟體工程師(以下簡稱工程師)的修養,或許能給那些初入職場或處於職場上升瓶頸期的讀者一些啟發。
我們現在的專案的程式碼提交資訊比較亂,所以很有必要建立一個程式碼提交規範。
下面就以3個不同工程師的處理方式來聊聊工作中的自我修養。
普通工程師
除非做過類似的工作,不然接到任務的第一件事一般是開啟瀏覽器搜尋“程式碼提交規範”之類的關鍵字,會發現相關結果很多。通過一番整理,得到下面的資訊:
提交資訊的編寫格式
<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>
type:提交型別,可選值如下
* work: 開發中(work in progress)
* feature:新功能(new feature)
* fix:修補bug(fix bug)
* doc:文件(documentation changes)
* style: 格式(change code format)
* refactor:重構(modify code but not feature)
* test:增加測試(test code)
* chore:構建過程或輔助工具的變動(changes don't modify src and test files, only config or tasks)
scope:
用於說明 commit影響的範圍,比如資料層、控制層、檢視層等等,視專案不同而不同。
subject:commit 目的的簡短描述。
body: 對本次 commit 的詳細描述
footer: 描述一些特殊情況,不相容變動和issue關閉。
複製程式碼
編寫提交資訊的工具
比如Commitizen
,基本操作如下:
# 安裝命令列工具
npm install -g commitizen
# 安裝依賴
commitizen init cz-conventional-changelog --save --save-exact
# 通過擴充套件命令提交
git add .
git cz
複製程式碼
把上面的編寫格式整理成文件,然後在專案中安裝依賴試用以下,任務完成~
進一步思考
但是這只是做為普通工程師的標準,優秀工程師該怎麼思考呢?
優秀的工程師和普通工程師的區別在於會反思工作並主動改進。也就是說不只滿足把事情做完,而是主動把事情做好。 把事情做好大致有兩種:
- 別人都能做的,但是你做得和別人不一樣。
- 別人不能做的但你能做。
顯然制定提交規範屬於第一種情況,所以優秀的工程師會進一步思考。
優秀工程師
目前的方案有沒有可改善的地方?
編寫格式
每次提交的資訊需要編寫的內容非常多,如果每次提交個程式碼像寫篇小作文一樣麻煩,必然會引起反感。 這就好比本來開車上班路上時間不到半個小時,但是現在要求低碳出行只能騎自行車要1個小時,這種規定的可行性就很低了。 所以精簡:
- 當檔案路徑較長或者數量較多時scope會變得很長,影響檢視subject。而且修改的檔案(夾)名稱也可以在查詢具體提交記錄的時候查詢出來。更麻煩的是如果提交的時候漏寫或寫錯了還會起反作用,所以省略。
- body和footer都屬於對提交的詳細描述,合併成可選項description。
提交工具
git cz
命令雖然可以替代git commit
命令來提交程式碼,但是它的有工程師不使用git cz
而仍然使用git commit
命令來提交程式碼則校驗就會失效。
所以需要一個校驗工具來保證我們的規範有效的執行,至於工具git早已經為我們準備好了——鉤子。鉤子類似於web元件的生命週期,可以在執行某些操作前後觸發對應的shell指令碼。與git commit
命令相關的鉤子有4個,按順序分別是:
- pre-commit。提交前觸發,不接收引數,可以執行一些檔案校驗的工作。
- prepare-commit-msg。提交前觸發,接收訊息引數,用於在提交之前附加一些內容。
- commit-msg。提交前觸發,可接收訊息引數,用於檢查提交訊息是否符合規範。
- post-commit。提交後觸發,可執行自動推送、部署程式碼等操作。
這裡我們選擇commit-msg
來實現,對應的指令碼會像下面的樣子:
#!/bin/sh
if grep -Eq "^(work|feature|fix|refactor|doc|test|chore|style|revert):\s*\w+" "$1"; then
exit 0
else
echo "Please format your commit message as follow:"
echo "<type>:<title>"
echo "<description>(optional)"
exit 1
fi
複製程式碼
目前的方案有沒有可以補充的地方?
形成規範
規範就像是制度,好的制度不僅需要制定者花心思去設計,更需要執行者知曉和配合。 所以有了文件和工具之後需要考慮的另一件事就是在團隊內部推廣。 推廣的方式常用的有做個PPT開會培訓一下,或者把資料放到團隊的wiki上提醒大家檢視,這裡就不詳述了。
再進一步
到了這一步,任務不僅做完了,而且也算是做好了。 但要實現個人的最大提升,優秀還不夠,必須卓越。 所以除了把事情做好之外,還應該考慮將它最大價值化。
卓越工程師
再回到例子中,這個解決方案有沒有可能用於其它團隊/場景?
通用性
編寫格式這一塊基本上沒有太多問題,但是提交工具會成為一個較大的障礙。Node.js通常只是前端團隊的工具。如果要在其它團隊中推廣使用,學習成本不說,還會在專案中引入額外的依賴,可操作性並不強。
那是不是也要針對其它開發語言的專案去找合適的解決方案?這當然可以但不見得是最好的方式,因為時間成本太高,最好的方式是找到一個通用解決方案。
還是鉤子
其實這個方案git早已經為我們提供好,還是之前用到的鉤子。雖然commitizen
這類Node.js模組不是跨語言的解決方案,但是其採用按步驟給出提示語,然後由使用者輸入的互動方式,對於不熟悉規範的人來說還是比較好的。所以我們可以在鉤子指令碼中沿用這種形式。
但對於熟悉規範的開發者來說可能希望直接使用git commit
命令一次性提交,所以還加入一些校驗——對於不符合規範的提交資訊給出互動提示,引導開發者按步驟完成提交資訊。由於指令碼內容較長,這裡就不貼出來了,感興趣的讀者可以去文末的倉庫地址中檢視。
完善
如果要做得更完美一些可以使用git提供的template功能,具體使用可以檢視文末提供的倉庫地址。
總結
工作態度決定了工程師的潛力,思考維度決定了工程師能力的天花板(當然這句話在別的崗位也可能通用)。
制定提交規範雖然只是一件很小的事,但是可以從中總結出不同級別工程師在這兩個方面的差異:
普通工程師 | 優秀工程師 | 卓越工程師 | |
---|---|---|---|
工作態度 | 公司安排什麼就做什麼、學什麼,缺乏主動意識。 | 能完成公司安排的任務,有時候還會超預期完成,同時在工作之餘會利用時間學習。 | 不僅能常常超預期完成公司的任務,同時還會主動思考團隊、產品現有的問題或可以改進的地方並給自己安排任務 |
思考維度 | 單一、點狀的。只關注任務本身,只考慮如何完成任務 | 線性、縱向的。會思考任務背後的目標,以及怎樣才能更好的達目標而不僅是完成任務 | 網狀,全域性的。切換身份思考,讓任務成果對組織產生最大價值 |
如果您覺得這篇文章對您有幫助請點贊,感謝閱讀~
參考文章:
《Commit message 和 Change log 編寫指南》
提交規範倉庫地址: