• 更新建置文件

  • 修復依賴陣列

  • 重構

  • 修復測試

  • *最有名的:***更新README.md** (感謝Github🤦)

這些是......我在上個月實際看到的一些令人驚嘆的提交訊息。 👀

而且......其中一些也存在於我們的程式碼庫中。

有點尷尬。我知道。 😅

但這是不行的🙅,理想情況下我想讓世界擺脫這些。

“當然,無論如何。即使讀完這篇博客,我也不認為任何事情都會改變。”

為了改變一切,我需要讓你相信:

  • 這帶來了您可以感覺到或測量到的真正差異

  • 這對其他人產生影響(稍後可能會歸因於您)

“好吧,繼續吧。我該怎麼做,我能從中得到什麼?”

寫得好的提交訊息有一些明顯的好處:

1. 🧑‍💻更容易除錯

git blame使我們非常容易理解為什麼要引入更改,並且可以更輕鬆地向作者詢問相關問題。

git blame並不是除錯過程中使用的第一個工具,但對於與業務邏輯相關的複雜問題,它是一個特別在大中型公司中發揮作用的工具。有些程式碼只是引發了這樣一個問題:“為什麼要這樣寫?”或「這最初是為了解決什麼目的?」。有些問題的答案不在於工程,而在於產品決策。寫這篇文章的作者最有可能知道其中涉及哪些決定。

無上下文偵錯

當然,即使不需要花俏的訊息git blame也會告訴你提交的作者。那為什麼是這篇文章的這一部分呢?

因為身為作者,您多久會記得您 6 個月前寫的投稿正在做什麼?特別是當它有像“重構”這樣的提交訊息時?運氣不好吧?

我見過更有經驗的開發人員編寫了非常有用的提交訊息。我認為他們中的一些人做得有點過頭了,但這裡有一個粗略的例子:

Fix crash on login screen due to null pointer exception.

- Checks for null values before accessing user profile data
- Adds unit test to cover this scenario
- Issue linked: BUG-5678

也許有點太多了,但如果不是很明顯的自動對焦就太糟糕了。

現在,當我需要除錯該領域的問題時,能夠為作者和上下文git blame可能是我的救星。

我這麼說是充滿信心的,因為我曾經在 Uber 既是給予者,也是接受者。

這有一個嚴重的額外好處,當您閱讀此部落格時,您可能會高估這一好處:

  • 為您和您的團隊節省時間,減少挫折感

在沒有上下文的情況下進行除錯是痛苦的。甚至不是那種你可以說「殺不死你的,會讓你更強大」的情況。因為它只會讓你感到沮喪。

你知道的。你的團隊知道這一點。這就是為什麼你試圖了解是誰引入了「那個錯誤」並與他們交談,卻發現他們兩年前離開了公司。祝你好運。 🤝

這樣,您就留下了一份遺產,讓人們深情地記住您,並希望他們能再次與您合作。

“如果我使用合併或壓縮提交怎麼辦?”

有些人對他們有強烈的支持或反對意見。

我要說的是,合併提交有助於在一定程度上包含提交中包含的 PR 上下文,但如果寫得不好,單一提交本身可能沒有太多與之關聯的上下文。

而且由於 PR 可能涉及各種不同的更改,這些更改一起工作以發布功能,並且構成更改可能有自己的上下文以這種方式編寫,因此壓制它們可能會有效地混淆所有上下文,從而很難從提交歷史記錄。

但無論哪種方式都可以寫出功能完善的軟體。只要你和你的團隊都同意你的合併 PR 的方式對你來說是可行的,並且問題最少,我是誰,我會干涉嗎?

2. 🔍 更輕鬆的程式碼審查

如果您的組織不太關心讓程式碼審查變得輕鬆,也不讓它感覺像是一件苦差事,那麼您需要與您的員工分享這一點:

{% 嵌入 https://dev.to/middleware/the-senior-engineers-guide-to-the-code-reviews-1p3b %}

現在,更好的提交訊息如何幫助程式碼審查?

根據Middleware 的分析資料,成熟程式碼庫(活躍的倉庫,經過其設定階段)中的平均 PR 可以約為 300 行。

有很多行。大多數這些更改都不會發生在同一個文件中。他們也不應該。 300 行位於可讀文件的上限(儘管這不是一成不變的規則)。

這幾乎可以保證這些 PR 中會提供不同類型的更改,這些更改需要組合在一起才能提供所需的功能。

如果您因任何原因無法建立較小的 PR,則可以在同一 PR 中進行較小的提交。使每個提交都包含最小的邏輯隔離更改,以便提交訊息可以充分解釋其包含的內容。因為您也不想編寫一段長的提交訊息,所以您需要建立一個足夠小的提交,大約 50-60 個字元可以解釋其內容。

現在,審閱者可以透過提交來審查你的 PR 提交,而不必跟進你的所有事情,或者想知道為什麼某些東西是這樣寫的(如果他們這樣做,他們將不得不問你[作者],你知道嗎?

有意義的提交訊息

3. 🚀 更好的發行說明!

或者,如果您沒有準確產生“發行說明”,那麼它仍然是專案歷史的更好文件!

具體來說,Github 還允許您根據提交自動產生專案的發行說明。很多人會查看發行說明來了解新版本包含哪些修復或功能。

請參閱React 程式碼庫的發布部分,並查看每個發布說明有多少反應!

反應發行說明

明確發布說明對人們很重要。透過編寫良好的提交,您可以節省編寫發行說明的精力。

最後...

4. 👥 鼓勵整個團隊更好的實踐

使用路克的力量

當團隊成員看到編寫良好的提交訊息的好處時,他們很可能會效仿。這可以導致整個團隊採用更嚴格的程式碼提交方法,從而鼓勵清晰和精確的文化。這就是讓SDE1 的思考和行為像 SDE2 一樣的東西。

這是此類提交的另一個範例:

Update permissions routing layer to handle subroutes independently.

- TKT-1234
- The permissions routing logic was previously coupled with its nested routes
- This change will allow you to move subroutes to any other parent route without also having to make any changes to how the permissions for that subroute are defined

在多人處理同一個專案的環境中,一致且詳細的提交訊息可以協調每個人的理解和期望,減少潛在的衝突和誤解,而不需要太多時間來阻止上下文共享。

當然,如果您能夠成為團隊或組織中更好的承諾訊息的擁護者,您會很樂意獲得由此帶來的任何好處,不是嗎? 👀

能夠異步工作的團隊,才是能夠有效率地工作的團隊。沒有人希望你的團隊在這樣的事情上遇到瓶頸。 👌

總結一下

好的提交訊息會帶來巨大的收益。 💪

為您和您所屬的團隊帶來收益。

更少的除錯時間、更少的挫折時刻、更好的文件、自動發行說明等。

作為所有這些改進的副作用,您甚至可能會注意到更快的程式碼交付、更少的審核等待時間、更少的返工週期!

繼續!您所帶來的所有效率改進都值得稱讚!

並且確切了解使用中介軟體等生產力智慧工具為您的團隊帶來了多少收益! 🚀

{% 嵌入 https://github.com/middlewarehq/middleware %}


原文出處:https://dev.to/middleware/not-heres-how-to-write-actually-good-commit-messages-hint-its-not-just-adding-commit-lint-j2i


共有 0 則留言


精選技術文章翻譯,幫助開發者持續吸收新知。