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 而不是花很多時間解釋複雜的東西給你聽。

參考資料