Code Review
Code review 的本質就是要讓我們的 codebase 能夠維持一定的健康度並且是不斷地進步的。 在留 Comment 的時候,Reviewer 會針對必要的改善給出建議,不過如果當有些 Comment 並不是那麼重要的時候,就可以在 Comment 的前面加上 Nit:
讓 Developer 了解這些 Comment 是可以先看看就好。
Code Review 的原則
- 要能給出技術上的建議,而不是個人偏好
- 應該要有共同一致的 Coding style 參考文件
- 沒有規則可以參考的時候 ,應該要讓 Developer 去 Follow 目前 Codebase 原來的做法以保持一致性。
Code Review 要看的東西
- Design
CL 的 code 是否 make sense?和其他的 Component 還是 Library 是否整合得宜? - Functionality
從功能面來看是否有達到原來的目標呢?對未來的使用者是否帶來益處呢? - Complexity
這一段 Code 是否寫得過於複雜? - Tests
Reviewer 應該要要求寫測試,最基本的就是 Unit test,再來可能有 Integration test,end-to-end test 等 - Naming
好的 Naming 要能夠清楚表達這是什麼,或者這是在做什麼,以維持可讀性。 - Comment
Comment 應該要寫的是,這段 Code 為什麼存在,主要是為了達到什麼效果 - Style
- Documentation
要注意這次的 CL 是否也要同步去修改文件的部分以同步。 - Every line
要能夠理解每行 Code - Context
即使改動的部分很少也是要通盤考慮,避免反而增加了系統的複雜度等。 - Good things
Review 的步驟
- Take a broad view of the change
- Examine the main parts of the CL
找出最多邏輯改動的那個檔案,當作是主要修改的部分 - Look through the rest of the CL in an appropriate sequence
如何撰寫 Comment
- 友善與尊重的語氣。對事不對人。
- 要充分給予說明。可以的話盡量提出會給這些建議的原因,例如是參考了什麼 Good practices。
- 在直接點出問題給出答案以及讓 Developer 自己做一些思考和決定之間取得平衡。記得把 Code 改好是 Developer 的責任而非 Reviewer 的。
- 鼓勵 Developer 把 Code 簡化或是留下 Comment 而不是花很多時間解釋複雜的東西給你聽。