Code-Review
一句話定義
由作者以外的人檢視改動，判斷它是否讓整體 codebase health 變好；核心不是找錯或追求完美，而是在品質、速度、可維護性與 developer 成長之間做工程治理。
核心要點
核心標準：better, not perfect
Google Code Review 準則的中心判斷是：只要一個 CL / PR 整體上明確改善系統的可維護性、可讀性、可理解性或功能品質，就應該傾向 approve；reviewer 不該為了「還可以更完美」而長時間阻擋。
反過來說，這不是放水標準：只要改動會讓 codebase 變差，即使時間壓力存在，也不該進 main；只有安全性、嚴重 user impact 等小範圍高優先級 emergency 才能用例外流程，且事後應補正常 review。
Reviewer 的四層判準
- 技術事實優先：review comment 要基於技術事實、資料、測試結果與軟體設計原則，而不是個人偏好。
- Style guide 是 style issue 的裁判：有 程式碼風格指南 就照共同文件；沒有寫進 guide 的偏好通常不應 blocking，最多標成
Nit:。 - 一致性是 fallback rule：若沒有其他規則，且不會降低 code health，就要求新 code 跟既有 codebase 做法保持一致。
- 不讓 CL 躺著：長期無共識時應同步溝通、找 maintainer / tech lead / manager 協助，而不是讓 PR thread 無限來回。
審查面向
| 面向 | Reviewer 要問的問題 |
|---|---|
| Design | 整體設計是否合理？是否屬於這個系統？是否與 component / library 整合得宜？ |
| Functionality | 是否做到作者想做的事？這件事對 end user 或未來 developer 是否有益？edge case / concurrency / race condition 是否想過？ |
| Complexity | 是否過度複雜或 over-engineering？是否為尚不存在的未來需求預先設計而模糊當前焦點？ |
| Tests | 是否有適當 unit / integration / end-to-end tests？測試是否真的會在行為壞掉時失敗？測試本身是否可維護？ |
| Naming | 名稱是否足以說明這是什麼、做什麼，而不過度冗長？ |
| Comments | comment 是否解釋 why，而不是重述 what？如果只靠 review tool 解釋，未來讀者看不到。 |
| Style | 是否符合共同 style guide？純個人偏好不應阻擋 CL。 |
| Documentation | 改動若影響 build / test / release / API / 使用方式，文件是否同步更新？ |
| Every line | 人寫的 code 原則上都應理解；看不懂通常是未來讀者也看不懂。 |
| Context | 不只看 diff，要看所在 function / file / system context，避免小改動累積成複雜度。 |
| Good things | review 也是 mentoring；好的做法也要指出，讓 developer 知道什麼值得延續。 |
Review 步驟
- Broad view：先看 CL description 與整體方向。若這個改動根本不該做，要立即、具體、禮貌地說明，避免作者繼續在錯方向上投入。
- Main parts first：找出邏輯改動最多、設計最關鍵的檔案或模組；若主設計有問題，先回覆，不必等看完所有小檔案。
- Rest in sequence：主設計過關後，依合理順序看完其他檔案；有測試時可先看測試，理解預期行為後再看實作。
速度：重點是 response time
Code review 太慢會降低整體團隊 throughput、放大 developer 挫折，甚至在時程壓力下促成低品質 CL 被合併。Google 準則強調的速度不是「一次把整個 review 做完」，而是讓作者快速知道下一步。
- 不在 deep work 中時，收到 request 後應盡快看；通常不應超過一個工作天。
- 正在專注 coding 時不必立刻中斷；在午餐、會議後或任務斷點回覆即可。
- 無法完整 review 時，也應先給 broad comments、預估時間或建議其他 reviewer。
- CL 太大時，要求拆成 self-contained 小 CL；這能提高 review 品質、降低 rollback / merge 成本。
Comment 寫法
好的 review comment 需要同時清楚與低防禦：
- 對事不對人：評論 code / design / trade-off，不評論 developer 能力或動機。
- 說明原因：讓作者知道這個要求如何改善 code health，而不是只看到命令。
- 標註嚴重度：
Nit:/ Optional / FYI 等標籤能讓作者分辨 blocking 與 non-blocking。 - 問題與方向平衡：修 code 是 developer 的責任；reviewer 不必替作者設計完整 solution，但要提供足夠方向。
- 把解釋留給未來讀者：如果 reviewer 看不懂，通常應簡化 code 或補 code comment；只在 review tool 裡解釋不會幫到後來維護者。
Pushback 與「下次再改」
Developer 可能比 reviewer 更接近 code；當 developer 的技術論證成立，reviewer 應承認並放下。若 reviewer 仍認為某要求會改善 code health，則應先確認自己理解對方論點，再補充技術理由並保持禮貌。
「這次先進、下次再清」通常是 codebase 腐化的來源：新工作會不斷到來，cleanup 很容易消失。若問題會實質降低 code health，通常應要求在本 CL 修好；若真的無法一次解，至少要建立 bug / TODO，清楚指向本次改動。
與其他概念的關係
- Pull-Request — PR 是現代 code review 的機構化介面；diff、行內評論、change request、CI 狀態與討論記錄都把 review 具體化。
- GitHub工作流 — feature branch → PR → review → squash merge 是 code review 的標準工作流外殼；本頁補的是 review 判準與溝通規則。
- 程式碼風格指南 — style guide 是 review 中處理風格分歧的共同裁判；沒有寫進 guide 的偏好不該成為 blocking comment。
- AI輔助開發 — AI agent 大量產出程式碼時，code review 是人類最後的品質治理層；不能因為 code 是 AI 產生或測試通過，就跳過 design / complexity / documentation 判斷。
- 完成的定義 — code review 常是團隊 Definition of Done 的一部分，但 DoD 更關心任務何時算完成；Code Review 更關心這個改動是否值得進 codebase。
- SBI溝通術 / I-Like-I-Wish-What-If / 把人跟問題分開 — review comment 是工程場景的建設性回饋；共同目標是降低防禦、提升行為改變機率。
- Google — Google Engineering Practices 的公開 code review 文件是本頁主要方法論來源。
相關來源
- 2026-05-06-Google-Code-Review — Ryan Yang 對 Google Code Review Guide 的中文整理；本頁主來源，提供 reviewer 標準、審查面向、速度、comment 寫法、pushback 與 emergency 判準
備註
建頁理由：Vault 已有 Pull-Request 與 GitHub工作流，但它們偏向工具介面與流程；本來源補上的是真正的 review 判準與溝通治理。若不獨立建頁，code review 會被誤收斂成「PR 的附屬功能」，無法承載後續 AI agent 自動 review、review culture、small CLs、comment severity、CODEOWNERS / branch protection 等擴展方向。
未來累積方向：(a) Google 官方 Engineering Practices 完整 ingest（reviewer + CL author 兩側）；(b) small CL / stacked PRs / Graphite 等流程工具；(c) CODEOWNERS / required reviews / branch protection 治理層；(d) AI 自動 review 的可靠性、誤報與人類交接；(e) 開源專案 review etiquette；(f) security / privacy / accessibility 等專門 reviewer 分工。