本文參考、翻譯自:[Link]

7個法則你須要遵守的

  1. 用一空行分開標題和內文
  2. 用 50 個字母以內,撰寫標題
  3. 標題的第一個字大寫
  4. 標題的結尾不要用句點結束
  5. 在標題列用祈使語句
  6. 以每 72 個字母以內,撰寫內文
  7. 用內文說明「What」「Why」、而非「How」

舉例來說:

Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The blank
line separating the summary from the body is critical (unless you omit 
the body entirely); various tools like `log`, `shortlog` and `rebase` 
can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you 
are making this change as opposed to how (the code explains that). 
Are there side effects or other unintuitive consequences of this change? 
Here's the place to explain them.

Further paragraphs come after blank lines.

- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded by 
a single space, with blank lines in between, but conventions vary here

If you use an issue tracker, put references to them at the bottom, 
like this:
Resolves: #123
See also: #456, #789

1. 用一空行分開標題和內文

並不是每一個 Commit Message 都有標題(subject)和內文(body)。常常一行標題就可以了,尤其是修改的內容太簡單,不用說明太多的情況。例如:
Fix typo in introduction to user guide
不用多說明什麼,因為如果想知道的話,可以用git showgit diffgit log -p查看。

你可以用-m的模式去git commit
$ git commit -m"Fix typo in introduction to user guide"

若是值得解釋的commit,就要寫內文了。舉例來說:

Derezz the master control program

MCP turned out to be evil and had become intent on world domination.
This commit throws Tron's disc into MCP (causing its deresolution)
and turns it back into a chess game.

這個用git commit,然後用VIM編輯就OK了!

若用git log顯示的時候覺得太冗長的話,用git log --oneline就可以顯示短的,只有標題的 commit 紀錄。

2. 用 50 個字母以內,撰寫標題

50個字母不是強制的,而是一種經驗法則。把標題寫在這之內可以提升可讀性,並且強制作者停下來思考,什麼才是最簡潔、準確的表達方式。

3. 標題的第一個字大寫

顧名思義。

要寫:

  • Accelerate to 88 miles per hour (O)

而非:

  • accelerate to 88 miles per hour (x)

4. 標題的結尾不要用句點結束

標點符號在標題出現是不必要的。

要寫:

  • Open the pod bay doors (O)

而非:

  • Open the pod bay doors. (x)

5. 在標題列用祈使語句

幾個例子如下:

  • Clean your room
  • Close the door
  • Take out the trash

用簡單的話說,就是可以使下面的句子通順:

  • If applied, this commit will “your subject line here”

例如:

  • If applied, this commit will refactor subsystem X for readability
  • If applied, this commit will update getting started documentation
  • If applied, this commit will remove deprecated methods
  • If applied, this commit will release version 1.0.0
  • If applied, this commit will merge pull request #123 from user/branch

6. 用 72 個字母以內,撰寫內文

git 不會自動換行、自動格式,因此當在寫 commit message 的時候,必須記得要手動換行。

最建議的格式是每行 72個字元,好讓 Git 有足夠的空間正常顯示文字。

在 VIM 的右下角就有字元統計,用 VIM 真的是寫程式的好工具呢!

7. 用內文說明「What」「Why」、而非「How」

這個 比特幣的 Commit 是一個很好的範例。他解釋了「什麼做了更動」和「為什麼做了更動」

commit eb0b56b19017ab5c16c745e6da39c53126924ed6
Author: Pieter Wuille pieter.wuille@gmail.com
Date: Fri Aug 1 22:57:55 2014 +0200

Simplify serialize.h’s exception handling

Remove the ‘state’ and ‘exceptmask’ from serialize.h’s stream
implementations, as well as related methods.

As exceptmask always included ‘failbit’, and setstate was always
called with bits = failbit, all it did was immediately raise an
exception. Get rid of those variables, and replace the setstate
with direct exception throwing (which also removes some dead
code).

As a result, good() is never reached after a failure (there are
only 2 calls, one of which is in tests), and can just be replaced
by !eof().

fail(), clear(n) and exceptions() are just never called. Delete
them.

大多數的情況下,我們不用寫出「做了什麼更動」的細節,因為好的程式碼會自行說明它在做什麼。所以只要著重在「What」和「Why」就好。之後維護你的程式的人會很感謝你的。

額外的小撇步

Pro Git ,有豐富的資源可以看,可以好好利用。

最後修改日期: 7 8 月 2020

留言

撰寫回覆或留言

發佈留言必須填寫的電子郵件地址不會公開。