Square 公司怎麼寫提交信息

前言

記得這個主題的分享不少，但經常還是會出現commit message 含糊不清或者為了偷懶都寫一模一樣的信息，這樣的提交信息最後如果代碼要回滾的話，造成的困擾就不少了。今日早讀文章由 @ 唐先僧翻譯分享。

正文從這開始~

解釋變化

在 Square 提交信息是很重要的交流形式，所以寫好提交信息是很好的為大家節約時間的方式。我們常常希望以前能夠做的更好。那些時候的提交信息仍然存在，並且很多仍然非常重要。

我們搜集了我們投入在出色的提交信息上的各種想法，這不僅是為了短期內節約我們的時間，從長遠來看也可以。現在我們將它們分享出來希望同時也對你的團隊有所幫助。

TL；DR： 優秀的提交信息解釋了變化

在 Square， 我們編寫了大量的代碼。最好的代碼應當是不言自明的。當我們的代碼表述性不夠的時候，就會有注釋來解釋這段代碼做什麼事情，或者更進一步，為什麼它要這麼做。一個開發者如果去閱讀 SHA 的代碼，他就能理解它做了什麼事情以及為什麼它要以那樣的方式去完成。

提交信息不是關於代碼的，它們是關於變化本身的。這是一個至關重要的差別，但是這個差別常常被忽視。

當我們進行提交時，我們會將一些理想狀態下很清晰、自解釋的代碼覆蓋其他一些很清晰、自解釋的代碼。不管修改前後的代碼有多麼清晰，這兩者之間仍然會有內容的差別。提交信息就是建立在這個差別之間的橋樑。

提交信息有兩個讀者

考慮下提交信息的讀者。一般分為兩類：代碼檢查者和挖墳者。

直接讀者應該是代碼檢查者，他需要決定是否接受這次改變，以及代碼的改變是否反映作者的意圖。代碼檢查者為了評估，則需要了解變化的背景，對他們而言，如果有信息可以為該代碼變化提供背景知識，而不需要通過修改前後的代碼來推斷，會容易很多。

從長期看，提交信息的讀者應該是某一位開發者，他嘗試修復軟體中的某一個問題、移除不再使用的代碼、在現有的代碼基礎上開發新的功能、或僅僅是做出相似的改變、或是這些事情中的幾個。有時候，某一位開發者嘗試理解過去的一個決定（通常是作者本人！）。這就是考古學，如果每一條提交信息都有一條幫助性的信息解釋這些改變，事情就變得非常容易。否則，挖墳者除了通過比較修改前後的內容來重建提交者的思考過程別無他法--這通常是不可能完成的任務。

事實上，它們有三個讀者

出色的提交信息還幫助我們晉陞我們最好的工程師。它們提供了一些內容和細節，可以幫助我們評估一個工程師日常工作的技術敏感度。同樣重要的是，出色的提交信息展示了我們作為溝通者的技巧和同理心。清晰書寫、有見解、有幫助的提交信息說明了一位工程師有遠見並且能為他人考慮。有技術能力、同理心和有效溝通都是在 Square 獲得晉陞的關鍵因素。

怎麼做

我們很明確

我們是在修復一個問題？我們會簡單的描述預期和實際的行為，以及改變是怎麼和問題關聯的。我們是在添加一個新功能？我們會總結一下這個功能。

要假設讀者對我們為什麼要做出修改是一無所知的，這很有幫助。對多數讀者來說，這是真實的---即使是最小的，最「明顯」的改變。寫下修改動機尤為關鍵。

我們很精準

這似乎是不言而喻的，但是在回應 review 或者其他的迭代過程中，很容易忽視提交信息的更新。為了防止不準確，提交者和檢查者通常會在合并之前雙重檢查提交信息。

我們會說明為什麼這次修改是安全的

尤其是我們在修改一些基礎功能代碼或者處理一些不同尋常的事情時，記錄下為什麼那麼做是正確的，這是非常值得的。將我們的考慮和想法寫到記錄中，會給讀者一些保障，以防萬一以後再出現問題。

用更多的背景指向來源

Jira是肯定的。設計文檔，google groups 中的跟帖，Slack 中的討論也是合適的。和變化相關的背景我們提供的越多，挖墳者就越容易理解。

當然，簡單的鏈接到一個 Jira 標籤或者是討論跟帖並不是非常有用。為什麼要讓讀者（他們可能不是在瀏覽器中閱讀這些提交信息）去其他地方了解這些變化呢？他們可能不耐煩，所以可能會丟失一些關鍵的細節。他們同時也可能無法查看這些信息！例如：曾經我們使用過 Github 企業版。現在 Github 所有的那些PR 信息都已經丟失。工具一直在改變，但是提交信息一直存在。

Jira 和 Stash 對獲取一些背景信息非常有幫助，用於理解決定修改時來來回回都發生了什麼。 我們的提交信息會捕獲來來回回的最終結果，即使鏈接無效了，提交信息也應該能獨立存在。

我們知道形式

我們的信息會被各種不同的工具和不同的場景閱讀--pull request， IDEs， git log 命令行可能展示精簡的或全部信息。關於書寫的形式需要了解這些重要信息：

1.提交信息有一個 主題行。 一條提交信息的第一行的前50個字元會被大多數工具特殊對待。在很多情況下，當通過 git log 輸出進行閱讀的時候，如果沒有其他操作，那麼就只能看到這50個字元。所以儘可能把你的提交信息概括到50個字元以內。如果可能，將 JIRA 的 issue ID 也包括在裡面。

2.多數工具希望在主題行和消息體之間有一個空白行。

3.提交信息常常是通過命令行工具閱讀，通常在左邊還會有分支線（「鐵路軌道」）。按行也寫是很有好處的，一般每行都控制在72個字元左右，肯定不要超過78個字元（為「軌道」留出空間）。

不跨界

我們在為我們的信息選擇形式的時候非常謹慎

架構和廣義決定寫到設計文檔中

當需要解釋代碼做什麼以及為什麼的時候，寫到代碼注釋中。

對於代碼改變，我們寫到提交信息中（你懂的！）。

最後，對於任何代碼評審者很關心，但是挖墳者不會關心的信息，寫到 pull request 的評論中。

注意：鼓勵以上幾條相互引用 ！

我們犯過的錯誤

正如你可能從上面可以看出的，很多想法都包含在一個很好的提交信息中，並且像大多數事情一樣，需要練習和相互幫助來建立習慣。 這裡有一些我們常見的錯誤。

模糊的手勢

我們有時會寫下這樣的信息 「Fix 」 或者 「Adds 」。有時這些信息並沒有描述這個 bug 或者是 functionality。這些僅僅是提示和線索，剩下的工作需要讀者去完成。

解釋代碼

描述新代碼和解釋變化是不一樣的。有時我們通過描述代碼的機制，來幫忙讀者理解這段代碼是如何運行的。然而代碼注釋應該更適合這種情況。有時我們嘗試解釋高層的設計或者架構，這些最好放在我們可以鏈接到的設計文檔中。不管是哪一個層面的解釋，都有比提交信息更合適的地方書寫。

將變化翻譯成字面意思

很不幸的是，這一點非常常見。匆忙之中，我們會寫簡單而直白的在信息中描述變化。「Deleted foo」，或者 「Rename bar to baz」。 這個意思是正確的，但是像這樣的信息太字面了。他們缺少上背景，動機，和閱讀者尋找的安全保障。

範例

過錯

這裡是我曾經寫下的真的沒有任何意義的提交信息。對不起，我的夥伴們！

commit ee46355557abe4ebc816f6cef9821e64c25b22f0

Author:Logan Johnson

Date:Wed Dec917:49:352015-0500

GET/account/status

diff--git a/common/services/src/main/java/com/squareup/server/account/AccountService.java b/common/services/src/main/java/com/squareup/server/account/AccountService.java

index da02d2f..20c7c43100644

---a/common/services/src/main/java/com/squareup/server/account/AccountService.java

+++b/common/services/src/main/java/com/squareup/server/account/AccountService.java

@@-48,11+48,11@@publicinterfaceAccountService{

*@deprecated use{@link #status()}

*/

@Deprecated

-@POST("/1.0/account/status")//

+@GET("/1.0/account/status")//

voidstatus(SquareCallbackcallback);

/** Queries the account status. */

-@POST("/1.0/account/status")//

+@GET("/1.0/account/status")//

AccountStatusResponsestatus();

/** Saves all preferences to server. Any null values will be left unchanged on the server. */

你可以看到它沒有提供任何變化的背景或動機，僅僅是描述了代碼。我不知道為什麼要將請求從 POST 修改為 GET。有 bug 嗎？也許吧，但是 bug 是什麼？是請求本身的問題？我在修復我們的 REST 庫裡面的一個 bug，現在可能已經修復了？這個變化應該在某一個時間點還原？使用 POST 具體的錯誤在哪裡，為什麼我使用 GET 就會好一些？這麼多問題！到現在我也不知道答案。

好一點的

我想我在這裡做的更好一點：

commit cb5f051c5ee95e795dedaf3a264062cf75d44b1e

Author:Logan Johnson

Date:Mon Aug814:41:042016-0400

don t register Transactioninmultiple scopes

RA-14998

TransactionBundler used to implement both Bundler and PausesAndResumes.

In order to correct a lifecycle tangle(obviousfromthe dual

implementation),we separated those two concerns and made Transaction

implement PausesAndResumes instead.That change was madeinthisPR:

https://stash.corp.squareup.com/projects/ANDROID/repos/register/pull-requests/10689/overview

Unfortunately,a side effectof(or possibly,motivationfor)having the

TransactionBundler implement PausesAndResumes is that we vend a

TransactionBundler instance to each caller.That instance would end up

getting registeredwithan Activity scope,which was safe since each

caller wouldgetanewinstance--even though Activity scopes overlap,a

single PausesAndResumes instance would only ever be registedwitha

single scope.

By making the Transaction implement PausesAndResumes,we created a

problem.Transaction is scoped to the Application,and outlives any

Activities.Since Activity lifecycles(and thus scopes)overlap,this

meant we would attempt to register the Transactioninan incoming

Activity scope(via PauseAndResumeRegistrar)whileit was still

registeredinthe outgoing Activity s scope.This caused a pretty

popular crash.

The fix here is toreturnto vending a PausesAndResumes object to each

caller,so that a separate instance is registeredwitheach Activity

scope,avoiding the dual-registration crash.

note:The attentive reader will see that it s not actually the

PausesAndResumes that gets registeredwiththe Scope.It s another

Scoped object that wraps the PausesAndResumes and delegates its

equals/hashCode.

diff--git a/register/src/main/java/com/squareup/payment/Transaction.java b/register/src/main/java/com/squareup/payment/Transaction.java

index fd09de4..1121c5e100644

這一次，我們有了更多答案。這裡有一些歷史介紹，包括介紹這個問題的鏈接，可以閱讀更多信息。為了讓讀者理解，我詳細描述了我修復的這個bug（至少我在8個月以後還能理解）。最後，有了這些背景支持，我簡單的描述了我做了什麼修改，以及為什麼這個修改可以修復這個問題。今天來看這個對我就有用的多，我希望對其他人也有幫助。

剛前面說的，此主題分享過很多，為你推薦：

關於本文

譯者：@ 唐先僧

譯文：http://www.jianshu.com/p/057159fde131

作者：@Logan Johnson

原文： https://medium.com/square-corner-blog/how-square-writes-commit-messages-8e92fcbf77c9

喜歡這篇文章嗎？立刻分享出去讓更多人知道吧！