關于Pull Request的十個建議

Pull Request 是 Bitbucket、GitHub 等源代碼托管系統為了方便開發者之間協作而提供的一個功能，它提供了一個用戶友好的 Web 界面來幫助審查人員進行代碼審查。開發人員可以通過 GitHub 發出 Pull Requests 要求請求他人將程序拉下來進行代碼審查。一個好的 Pull Request 不僅僅只是代碼的事情，還牽涉到代碼審查者對代碼的審查，所以開發者不僅要寫出好的代碼，還必須迎合審查者的審查工作，才能給使得自己貢獻的代碼順利通過 審查并合并到 master 分支。現對丹麥的程序員、軟件架構師、獨立顧問 Mark Seemann 在自己博客中發布的一篇題為《關于 Pull Request 的十個建議》的文章進行一個全面的整理，以供讀者閱讀和參考。具體內容如下：

1. 進行較小的 Pull Request

一個小且集中的 Pull Request 會使得提交的代碼更加容易通過審核。據 Mark Seemann 根據自己的經驗透漏，對提交代碼進行審查所花費的時間是隨著代碼大小呈指數增長，而非線性增長；Pull Request 多大才合適與 Pull Request 做了什么相關，最好少于 12 個文件的改變。如果 Pull Request 非常大，審查者就需要安排連續、相對比較長的時間進行審查，就會造成審查過程的延遲。

2. 每個 Pull Request 只做一件事

就如軟件設計模式中的單一責任原則所指：一個類只負責一個功能領域中的相應職責，因此一個 Pull Request 也應只關注一件事情。如果一次 Pull Request 做了多件事情的話，將會增加審查過程的延遲、審查被拒絕的可能性。

3. 注意代碼行的字數，最好少于 80 個字

代碼審查者會使用不同的審查工具來審查提交的代碼，并且 GitHub 和 Stash 還提供了不同形式的視圖，這樣就使得代碼審查者能通過不同視圖非常方便來審查用戶的提交。如果代碼行比較寬的話，審查者就不能在一個屏幕或者半個屏幕中來 閱讀代碼，不得不拖動滾動條來閱讀代碼。為了使得代碼比較容易審查，每行代碼最好少于 80 個字符。

4. 避免重新格式化代碼

就算自己覺得應該改變當前代碼的格式以適合自己的風格，但是請不要這么做。在源代碼上，用戶對每個字節的改變將會在不同的審查視圖顯示出來。有 些審查者會選擇忽略空格改變，但是有些審查者會審查這些代碼，對這些格式化引起的代碼審查屬于不必要的審查。如果真需要解決空格問題的話，就需要在其他文 件里移動代碼、改變格式或者對代碼做其他樣式改變，并在 Pull Request 注釋中給出相應的說明。

5. 確保代碼能夠編譯通過

在提交 Pull Request 時，應該首先在自己的電腦上進行編譯構建。在編譯構建過程中，務必注意編譯過程出現的警告，要把警告當作錯誤來對待，這些警告可能不會阻止編譯，就有可能 被忽略。然而，當用戶 Pull Request 操作引起了很多編譯警告的話，代碼審查者就有可能拒絕對應的提交。

6. 確保提交的代碼能夠通過所有測試

即使問題代碼已經做了自動化測試，但是在提交 Pull Request 時，也要務必保證針對代碼的所有測試都必須通過。

7. 添加測試

為代碼建立測試規則，即使出現問題的代碼已經做過了自動化測試，最好也要為自己提交的代碼也做下測試。

8. 記錄下自己提交的原因

利用文檔對代碼進行注釋、對自己的代碼直接進行注釋、利用版本控制器提供的提交信息功能備注信息、利用 Pull Request 管理系統（如 GItHub 或者 Stash）添加自定義的 Pull Request 注釋信息。

9. 編寫符合編碼規范的代碼

按照代碼正確性規則編寫代碼，并附上有效的代碼注釋、提交信息、Pull Request 信息等。

10. 避免顛簸

不同審查者對 Pull Request 有可能具有不同的觀點，這就會導致顛簸的情況，就需要用戶移除沖突的提交和推送修改的分支，并備注有效的信息。