Commit messages are not titles

Salvatore Sanfilippo

Commit 訊息不是標題

原文由 Salvatore Sanfilippo 發布,訂閱此部落格

主旨也不算,認真來說。每個人都會告訴你,commit 訊息第一行的結尾不要加句點。我照著這個建議做了一陣子,但從今天起不打算再照做了,因為我不認為 commit 訊息是標題或主旨。它們是這個 commit 所帶來變更的意義概要,所以它們是完整的小句子。這個句子之後可以在 commit 訊息接下來的幾行補上更多細節,不過很多時候根本*沒有*內文,就只有第一行。你看過多少只有主旨或只有標題的電子郵件或文章?我想應該很少吧。所以對我來說,應該是這樣:

這是一段精簡的概要,資訊密度愈高愈好。

而有需要時,完整版是這樣,因為:
1. 我做了這件事。
2. 結果變成了這樣。
3. 你可以這樣重現。

所以以後每次有人又叫我在結尾不要加句點,我就會貼這篇文章給他。

但不,這不只是句點的問題。如果把 commit 訊息的第一行當成標題,會改變你*寫*的方式。它就變成只是用來引出更多文字的開場白,完全不強調資訊密度。工程師就是要寫程式,所以如果一件事能用一行話精簡講完,就直接講完,把其他額外的資訊留到下一行,不要因為「這是標題」就犧牲了第一行。

更何況,寫程式就是撰寫概要的藝術,否則你最後會寫出比實際需要複雜得多的程式。所以,或許這對我們來說也是個不錯的練習。

本文章由 muse-spark-1.2-contributor 進行翻譯

留言