如何建立和執行 Code Review

好處

可以成為工程師

壞處

不能成為工程師

前置作業

在開始進行 Code Review 之前,可以先按照以下步驟來進行

建立檢查清單

建立一個檢查清單可以列出三項(必要清單、專案清單、邏輯清單),以下只是範例。

必要清單

每個 PR 都一定要符合的項目

  • Branch 命名 和 Commit haed 是否符合格式
  • Commit body 描述符合格式
  • Coding style 是否符合規範
  • 檔案結構和命名是否符合規範
  • PR/MR 的 Title 和 Description 是否符合規範
  • 是否包含測試資訊和腳本,和測試後的截圖或報告
  • 相關文件是否更新
  • 是否包含了金鑰或密碼敏感資訊

專案項目

各專案一定要符合的項目,例如 Website、APP、Backend、SRE 的專案各自需要注意的規範

  • Website:
    • 是否包含符合 UI 設計
    • RWD 是否通過
  • APP:
    • 是否符合 UI 設計
    • OS 的版本或平台是否驗證
  • Backend
    • API 文件是否編寫並更新
    • 更動 Database Schema 的話是否有做版本控制腳本
  • SRE
    • 是否有更新架構圖
    • 調整後的成本預估

邏輯清單

用於 Reviewer 在 Review 時應該要注意的地方

  • 是否 Thread-safe
  • 是否有 Race condition 的 Side effect
  • 效能上是否更好的作法
  • 邏輯上是否符合 Ticket 要求
  • 是否跟文件描述相同
  • 修改範圍是否太多
  • 測試是否符合:獨立性、唯一性、符合 Ticket 所需、是否有沒思考到的測試情境
  • 檢查程式的邏輯、可讀性、模組化、複用性、錯誤處理

規劃流程

前置的三項清單都列完後,開始就是規劃流程。一般 Reivew 上有以下執行階段

  1. Pre-commit hook / Pre-push Git hook
  2. PR created(CI Pipeline)
  3. Reviewer starts review

第一步先區分出清單上,哪些可以自動化,哪些不行。而自動化的項目又各自要在哪些階段來執行。

  1. Pre-commit hook / Pre-push Git hook:
    • Linter 檢查 Coding Style
    • Regex express 檢查 Branch 命名和 Commit
  2. CI Pipeline:
    • SonarQube 弱點掃描
    • Test 腳本執行

人工審核

這一步開始就是 Reviewer 的工作了,在這一步將無法自動化的項目來檢查。因為大部分的條件都已經檢查,因此在這一階段應該更專注在邏輯上

建議

  • 可以的話跟作者一起審核,節省來回討論的時間。或是善用 IDE plugin 或通訊軟體,將 PR 的事件串接起來有更快速的通知
  • 每個 PR 拆分的越小越好,因為相關的檔案越多,要考慮影響就更多。要釐清和審核上的時間也相對的越長。如果無法的話,也可以嘗試拆分成不同的 commit。例如文件修改、測試、邏輯更新各自為不同的 commit
  • 多人審核,可以給不同部門的人審核。例如資安部門、SRE。不同領域的人來審閱

Reference