從一件小事聊聊軟體工程師的自我修養 | 掘金年度徵文

亞里士朱德發表於2019-01-14

思考:如果讓你制定程式碼提交規範(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. 別人都能做的,但是你做得和別人不一樣。
  2. 別人不能做的但你能做。

顯然制定提交規範屬於第一種情況,所以優秀的工程師會進一步思考。

優秀工程師

目前的方案有沒有可改善的地方?

編寫格式

每次提交的資訊需要編寫的內容非常多,如果每次提交個程式碼像寫篇小作文一樣麻煩,必然會引起反感。 這就好比本來開車上班路上時間不到半個小時,但是現在要求低碳出行只能騎自行車要1個小時,這種規定的可行性就很低了。 所以精簡:

  1. 當檔案路徑較長或者數量較多時scope會變得很長,影響檢視subject。而且修改的檔案(夾)名稱也可以在查詢具體提交記錄的時候查詢出來。更麻煩的是如果提交的時候漏寫或寫錯了還會起反作用,所以省略。
  2. 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功能,具體使用可以檢視文末提供的倉庫地址。

總結

工作態度決定了工程師的潛力,思考維度決定了工程師能力的天花板(當然這句話在別的崗位也可能通用)。

制定提交規範雖然只是一件很小的事,但是可以從中總結出不同級別工程師在這兩個方面的差異:

普通工程師 優秀工程師 卓越工程師
工作態度 公司安排什麼就做什麼、學什麼,缺乏主動意識。 能完成公司安排的任務,有時候還會超預期完成,同時在工作之餘會利用時間學習。 不僅能常常超預期完成公司的任務,同時還會主動思考團隊、產品現有的問題或可以改進的地方並給自己安排任務
思考維度 單一、點狀的。只關注任務本身,只考慮如何完成任務 線性、縱向的。會思考任務背後的目標,以及怎樣才能更好的達目標而不僅是完成任務 網狀,全域性的。切換身份思考,讓任務成果對組織產生最大價值

如果您覺得這篇文章對您有幫助請點贊,感謝閱讀~


參考文章:

《git commit觸發的hook》

《Commit message 和 Change log 編寫指南》

提交規範倉庫地址:

github.com/yalishizhud…

相關文章