iT邦幫忙

第 12 屆 iThome 鐵人賽

DAY 28
0
Software Development

邁向專業軟體工程師必修的英文課系列 第 28

Day 28 – [修辭三] git comment -m "write a good comment"


程式有兩百萬個理由要修改,但寫git comment的理由絕對不是只是因為他是必填欄位。寫comment的意義在於未來可以知道這個push或是check in的理由是什麼,可能跟著那張ticket或者user story修改的,相關的背景知識,以及可能要注意的地方。
如果只是寫
git comment -m "code changes"
這樣跟沒寫是一樣的。
我可以這麼說:從第一天到現在,git comment是最容易,也唯一可以表現個人特質的地方:是否是個專業的工程師,就只要看git comment就知道了。

言簡意賅

當然,也不是要像寫文件一樣的寫comment,但至少要表達一個重點:為什麼要簽入這個修改?
所以,不要寫成這樣

git comment -m "code changes"

應該要把修改的理由寫出來。

git comment -m "fix issue #2738 that transaction logs are not saved into the database"

comment的時態和語態

不管是英文或者中文,在寫Comment的時候,都是過去發生的事情,所以用過去式描述很合理。但是git社群通常都還是建議用祈使句

[[imperative-mood]]
Describe your changes in imperative mood, e.g. "make xyzzy do frotz"
instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
to do frotz", as if you are giving orders to the codebase to change
its behavior. Try to make sure your explanation can be understood
without external resources. Instead of giving a URL to a mailing list
archive, summarize the relevant points of the discussion.
Ref: https://git.kernel.org/pub/scm/git/git.git/tree/Documentation/SubmittingPatches?id=HEAD#n133

試著說個好故事

如果你常常覺得年底的KPI不知道要寫什麼,那花個五分鐘寫好git comment會讓你省力很多:趁著記憶還清晰的時候,把整個修改的過程:特別是要Merge back的那一筆,好好的把整個過程寫清楚。

    之前的簽入編號681d646修改到Accounts.js,其中在認證會員的程式碼修改了
    對中華電信客戶認證的過程,但NP的會員並沒有被考慮進去。
    和上游廠商確認後,將相關的API做了修改,並且改善了SendSMS()的效能問題。

    Fixes bug #2749

不但年底的KPI就有素材可以寫,連履歷表都有故事可以說。

Comments的讀者是誰?

不管專案的repository是否會公開,會看到Comments的人除了工程師自己以外,同組的人,未來的菜鳥,PM,主管,還有很多人都會看到這個Comments。
所以,如果在Comment裡加了"黑話":

Asgardian在處理TTY的時候常常Stone,修改了處理流程確保不會再發生。

可能會增加閱讀上的困難。
盡可能的白話描述問題,讓讀者知道真實的問題是什麼。

養成好習慣,把git comment寫好,它會幫助你知道過去發生過什麼事情,也會讓未來的工程師看到整個歷史的過程,對專案的維護會帶來很好的幫助。


上一篇
Day 27 – [修辭二] Log - 凡走過必留下痕跡
下一篇
Day 29 – [修辭四] Issue report - Houston we have a problem
系列文
邁向專業軟體工程師必修的英文課30
圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言