Github 官方給出的代碼審查指導原則

這篇文章的內容由github官方提供，指導你如何在github上進行代碼審查和如何讓別人審查自己的代碼。

針對所有人的審查

• 接受這樣的事實：很多編程上的主張都是一種個人觀點。應該討論它們的利與弊，提出你的傾向觀點，迅速的達成一種解決方案。
• 提問，而不是命令。(「把這個變量命名成:user_id你覺得怎樣？」)
• 請求說明。(「我不明白。你能解釋一下嗎？」)
• 避免代碼的歸屬之爭。(「我的」，「不是我的」，「你的」)
• 避免使用一些會被認為是有關人身特徵的詞語。(「笨蛋」，「愚蠢」)要把所有人都看作是有魅力的、聰明的、善意的。
• 要明確。要記著並不是每個人都能理解你的意圖。
• 要謙虛。(「我不能確定——我們來分析一下。」)
• 不要用誇張修辭語。(「總是」，「從不」，「永遠」，「毫無…」)
• 不要諷刺。
• 展現真實的你。如果你不是幽默型的人，不喜歡使用一些表情符號或動畫gif圖，不要勉強。如果你是這種人，請自信的發揮。
• 如果有太多的「我不理解」或「另一種方案：」的評論，請專門針對這個人進行交流。可以把你們線下的交流總結成一個帖子附在後面。

讓別人審查你的代碼

• 對審查者的建議表示感激。(「謝謝提醒。我會把它改正。」)
• 理解審查是對事不對人。審查的是你的代碼，而不是你。
• 解釋為什麼代碼寫成這樣。(「因為xxx原因我才寫成這樣。如果我把這個類/文件/方法/變量改個名會更清晰些嗎？」)
• 整理所作的改動，在以後的迭代中重構它們。
• 在做修改的版本上註明代碼審查的連結。(「Ready for review: http://github.com/organization/project/pull/1″)
• push提交要基於最早的一輪反饋，並形成一個獨立的分支。等這個分支上的任務完全完成了再合併。這讓審查者能夠根據早先的反饋找到你的單獨的更新。
• 努力站在審查者的立場上理解。
• 爭取回復每個評論。
• 直到最後一個人退出登錄後再合併分支。
• 直到持續集成測試(TDDium, TravisCI,等)告訴你這個分支的測試套件通過後再合併分支。

代碼審查的過程

先要清楚你提交的代碼的必要性(是修補bug，提升用戶體驗，重構…)。然後：

• 針對你感覺非常好的地方以及不是很好的地方與作者交流。
• 找出既能解決問題又能簡化代碼的方法。
• 如果討論變得過於哲學或理論，把討論轉到線下，做成一個有規律的每周五下午的討論會。同時，是否採用你提出的實現方案，讓作者自己做決定。
• 提出你的實現方案，但要表現出作者也在考慮這種方案。(「你覺得這裡用一個自定義校驗如何？」)
• 努力理解作者的立場。
• pull請求登出時，加一個 👍 或「可以合併了」的注釋。

關於程序風格樣式的評論注釋

審查者應該對那些不符合樣式指導的地方進行注釋。例如這樣注釋：

[Style](../style):> 按名稱的字母順序排列多個路由。

對上面這個提醒的一個回復的例子：

哦。你眼真尖，謝謝。已在 a4994ec 修復。

如果你不同意某個指導原則，請在指導repo裡創建一個問題，而不要再代碼審查中爭論它。同時，請運用這個指導原則。