在 GitHub 上提交代碼必備指南!

【CSDN 編者按】你是否經常參與開源項目?如果在 GitHub 上參與開源項目的 Pull Request,你知道正確的做法是什麼嗎?別擔心,本文爲你準備了詳細的指南,希望對你有一定裨益。

作者 | Nick Skelton     

譯者 | 彎月    責編 | 蘇宓

出品 | CSDN(ID:CSDNnews)

以下爲譯文:

如果你是 PR 的作者

==================

1. PR 不宜過大

將拉取請求(Pull Request,即 PR)控制在很小是一門藝術。在編寫代碼的時候,你經常會有重寫、重構代碼或整理代碼的格式的衝動,但總的來說,優秀的開發人員會抵制一次性修改所有內容的誘惑。他們會集中一個目標,並將需要更改的代碼量降到最低。有些人甚至會相互比較 “刪除的代碼行數” 與“增加的代碼行數”比率。如果你需要重構和優化代碼,那麼請分別進行。不要找藉口將所有改動都塞到一個  PR 中,這是懶惰。

相反,你應該想辦法將 PR 控制在很小,這纔是創造力。

2. 自我審查

創建好 PR 後,你應該進行全面的自我審查。在完成一段代碼之後,你可能迫不及待地想將代碼推送到 PR,然後等着其他人發現錯誤,尤其是你花了好幾天的時間完成了一項比較大的改動時。別偷懶,要自律,你的工作還沒有結束。

你可以在自我審查中,問問自己:“這個名字好嗎?有沒有更好的?” 或者,“這個真的可以爲 null 嗎?” 通過這樣的問題,你不僅可以檢查自己的代碼,還可以在日常的編程工作中建立自我反思的好習慣。換句話說,這種自我審查的過程可以讓你成爲更好的開發人員。

3. 去掉不必要的文件

在自我審查的時候,你會經常發現某個文件只改了一些空格、調整了格式、優化了導入或一些文本更改,這些改動對 PR 根本沒有影響。

遇到這種情況,你應該重新打開分支,將這些文件還原回去,你只是做了一些略微的改進,功能上沒有變化,而且多餘的文件出現自 PR 中只會給審覈代碼的人帶來負擔,尤其是 PR 比較大的時候。

如果格式化很重要,請創建一個單獨的 PR,然後在 CI 中添加一個格式化的工具,並利用工具整理整個應用的格式。但是,避免這些不必要的文件很重要,這是對代碼審覈者的尊重。此外,這些無關緊要的變動還會污染 git 的歷史記錄,讓人們很難通過這些歷史記錄找到文件某些更改背後的意圖。

4. 創建有意義的標題

一般,標題我們都會照抄分支名稱或相關的票據。關於標題的規則只有一條,即遵循某種約定,建立簡潔而又意義的標題,基本思想與分支命名一樣。

創建拉取請求也是創建文檔,保持拉取請求的歷史記錄易於瀏覽,可以方便搜索過去的決策和思考過程。

5. 有意義的描述

再次強調,你應該將 PR 視爲文檔,一篇經常會被閱讀的文檔。PR 的描述應儘可能全面,但要簡潔,儘可能做到透過描述看懂你的意圖和決策過程,無需花時間討論。

有一種有效的方法是建立 PR 模板。模板的內容應與團隊達成共識,並隨時間的推移進行開發和調整,下面是給新手的一些建議:

6. 確認每條評論

在遠程異步通信中,有一點很重要,你需要向對方傳達你看到了評論。有時,只需要一個簡單的表情符號。無論評論多小,都不能忽視,尤其是在新團隊中。一旦與團隊建立融洽的關係,你就可以順其自然了,因爲你們之間互相都瞭解。但是,剛開始的時候,一定要有禮貌,注意言辭,以及個人的行爲。

7. 合併需要徵求每個人的同意

說起禮貌,你應該耐心等待別人提出意見,然後積極地給予迴應。如果等待的時間過長,你可以通過電子郵件和即時消息詢問,或者直接去找他們,讓他們知道你還在等待。

在我看來,如果你們團隊成員超過了 3 個人,則不必讓每個人都審查每個 PR。制定一個系統來確定由誰來審查每個 PR,比如讓每個人負責一些模塊;如果你是新手,則可以讓架構師 / 高級開發人員審查你所有的 PR。

如果你是審查者

下面的一些建議也同樣適用於代碼作者回複評論。

8. 簽出代碼

你的計算機上應該始終保有一個項目的兩個克隆:一個用於正常工作,一個用於審查 PR。這樣審查 PR 的時候,就不會影響到當前的任務了。

簽出分支後,點擊構建,並保持運行狀態,同時切換到瀏覽器。

9. 閱讀標題和說明

如果有人花了很大力氣編寫了自己的 PR 指南,那麼你至少應該耐心地讀完。在等待 PR 在你的另一個項目克隆上構建的同時,請閱讀相關的票據,閱讀 PR 的標題和說明,並提出你的審覈意見。

10. 在本地驗證你的建議

如果發現可以改進的地方時,請嘗試在本地克隆中修改代碼。當你是項目的新成員時,這一點尤爲重要。即便你提出的建議無法實現,或者甚至根本編譯不過去,也不必感到尷尬。在自己的 IDE 中修改代碼,如果成功,你會收穫滿滿的成就感;如果失敗,你也會慶幸沒有打擾到別人。

在確認你的建議可行後,不要讓自己的工作白費,你可以將代碼複製過去,放入 PR 註釋中,這樣作者就可以直接複製了。

11. 如果建議太大,就直接寫成 PR

如果你發現自己的建議太大,那就不要浪費精力,直接在他們的分支上建個分支,然後創建一個 PR,合併到原來的 PR 中。這種 PR 不需要常規 PR 的花哨功能,因爲它只是評論的一部分,可以讓你們做進一步的探討,然後由原作者考慮修改,最後如果一切順利,則合併到主 PR 中。

12. 抵制評論的衝動

發表評論時,我們往往情不自禁說個滔滔不絕。剋制這種情緒的關鍵是設身處地爲他人着想。不要忘了回顧一下所有的評論,仔細想一想有多少評論確實會被多方接受,而且能儘快實現。

以下是一些關於評論的技巧:

13. 如果沒有更好的替代方案,請不要發表評論

如果你不喜歡代碼的寫法,請提出更好的方法,否則還是閉嘴。

14. 要有信心,不要偷懶

不要使用 “也許”、“我不知道”、“如果”、“我不確定” 之類暗示懷疑的詞語。如果不確定,那麼請反省一下,爲什麼你不確定。或者也可以做一些實驗和研究,找回自信。

15. 修改代碼之前先模仿原來的風格

每個人都有自己的風格,而且都對比較執着於自己的風格。剛加入新團隊時,現有成員通常都會捍衛項目的現狀,而新成員則會表達 “他們的前一個項目有何不同,或者如何更好地完成工作” 等看法。

適應現有的風格,可以讓你儘快融入心團隊,而他們也更願意針對某些重要的方面提出建議,比如 SDK 的選擇、體系結構決策以及模式和實踐等等。在你完全掌握了他們的風格之後,再提出現代化的風格,他們更容易接受。

**16. 挑剔是好事 **

有時,同事審查你的代碼,只提出了一些風格上的意見,看似很挑剔,你也會感到沮喪。

但是,你應該這樣想:審查者已經很難找出你代碼中的實際問題。

遇到挑剔的意見,比如關於風格的註釋,你可以禮貌地強調 IDE 工具可以自動處理好 90% 的樣式問題。

17. 面對面的交流

有時,你們兩人針對某個 PR 的評論,反覆爭論不休。這個時候,你應該冷靜一下,然後寫一封郵件,約個時間面對面的交流。

網上的交流有時候來來回回,很浪費時間。還不如到會議室,面對面的交流,但切記冷靜,反覆思考自己的觀點,而且一定要保持客觀。面對面交流的目的是尋找最佳解決方案。

18. 心平氣和

建立 PR,難免被審查者指出問題。所以,首先最重要的就是:挑刺。但是你需要專業地挑刺,不要帶個人情緒。

請注意解讀評論的方式,有些人並不是故意的,他們只是沒有過多的思考,很着急,或表達能力不夠好。他們提的意見都是出自善意。

19. 沒有緊急的 PR

PR 之所以流行,有兩個原因:

  1. 異步交流。開發人員可以隨時進行審查和響應,這樣可以避免自己的工作被打斷或受干擾。

  2. 質量保證。在代碼進入目標分支之前,對其進行檢查和測試,以確保目標分支保持乾淨。通過隊友發現日常使用的代碼中的潛在問題。

如果你必須在 10 分鐘內合併分支(一般非常不推薦這種做法),那麼就不要發送消息要求別人立即審覈代碼,直接合並就行了。不要爲了流程而打擾別人。如果你必須在短時間內合併分支,那麼就找一個人進行結對編程,或者直接合並 PR。

總結

PR 是一個很好的習慣。在過去十年中,我所從事的大多數項目都採用了這種標準的做法,如今我仍在新項目中學習關於 PR 的新知識和流程。

上述建議不一定適合所有項目,與制定嚴格的規則和流程相比,組建團隊更爲重要。在團隊中,我們要友善待人,但也要有信心和紀律,同時以身作則,嚴格要求自己。

原文鏈接:https://medium.com/google-developer-experts/how-to-pull-request-d75ac81449a5

本文由 Readfog 進行 AMP 轉碼,版權歸原作者所有。
來源https://mp.weixin.qq.com/s/QhjL4tYLljRRwt3eMVI0Mw