2026-05-06-Google-Code-Review

Properties2
tags來源/文章, 狀態/草稿, 領域/開發, 主題/code-review
aliases讓 Google 教你 Code Review!, 讓 Google 教你 Code Review, Google Code Review 中文整理

閱讀時間約 30 分鐘

讓 Google 教你 Code Review!

後設資料

一句話濃縮

Code-Review 的目標不是追求完美或展現 reviewer 權威，而是用技術事實、可維護性、測試、可讀性與溝通品質，讓整體 codebase health 持續改善。

提取要點

  • 核心標準：只要 CL 整體上讓 codebase 在功能、可維護性、可讀性或理解性上變好，就應該傾向 approval；追求的是 continuous improvement，不是 perfect code。
  • Reviewer 權責：要把關不讓會腐化 codebase 的 CL 進來，但也不能用大量低優先級建議抑制 developer 的改進意願。
  • 技術判準優先：review comment 應基於技術事實、資料、共同 style guide 與軟體設計原則，而不是個人偏好。
  • Nit: 標籤：低重要度、純教育或可選擇忽略的 comment 應標示為 Nit:，避免 developer 把所有 comment 都理解為 blocking。
  • 審查面向：design / functionality / complexity / tests / naming / comments / style / documentation / every line / context / good things。
  • Complexity discipline：要防止 over-engineering；保持未來可修改的彈性，不代表為尚未出現的未來需求先設計通用介面。
  • Tests 也是 codebase 的一部分：測試不是衝 coverage rate，而是保護 codebase 的生產級資產，同樣需要 readability、maintainability 與合理複雜度。
  • Comments 寫 why，不寫 what：若 code 本身看不懂，優先簡化 code；review tool 裡的解釋不會服務未來讀者。
  • Review speed：重點是 response time 而不是一次完成所有 review；通常不應超過一個工作天，但也不應打斷專注工作流。
  • Small CLs：過大的 CL 會降低 review 品質、拖慢節奏並增加 rollback / merge 複雜度；應要求拆成 self-contained 的小 CL。
  • Comment 寫法：友善、對事不對人、說明原因；在直接給方案與指出問題讓 developer 自行解決之間取得平衡。
  • Pushback 處理：developer 可能比 reviewer 更接近 code；若其技術論證成立，reviewer 應承認並放下；若仍會改善 code health，reviewer 應清楚說明並堅持。
  • 不要讓 CL 躺著：長期無共識時應 face-to-face、找 maintainer / tech lead / manager 協助，而不是在 comment thread 無限來回。
  • 「下次再改」風險：現在不修，通常以後也不會修；若會腐化 codebase，應要求本 CL 先修好。
  • Emergency 例外：真正緊急通常是小範圍但高嚴重性問題（安全性、嚴重 user impact）；可以先針對正確性快速 review，事後再完整補 review。

提取概念

連結到此來源衍生 / 更新的 wiki 頁：

Ingest 筆記

2026-05-06

候選掃描：

  • Code-Review — 新建。Vault 既有 Pull-Request 處理的是平台介面與合併流程，GitHub工作流 處理 branch / PR / merge 的流程，程式碼風格指南 處理風格規範；本來源提供的是 review 本身的判準、溝通、速度與衝突處理，應獨立成概念頁。
  • Google — 已存在。補入 Engineering Practices / Code Review Guidelines 作為 Google 在工程管理與 codebase governance 的公開文件脈絡。
  • Pull-Request / GitHub工作流 — 已存在。補入「PR 是 Code Review 的機構化介面，但 review 判準不等於 PR UI」。
  • 程式碼風格指南 — 已存在。補入 style guide 在 review 中的權威角色：style guide 是 style issue 的裁判，未寫入 style guide 的偏好不應 blocking。
  • AI輔助開發 — 已存在。補入 code review 作為 AI agent 大量產出程式碼後的人類品質閘門：AI 產出仍要經過 design / functionality / complexity / tests / docs 等面向驗證。

未新建候選：

  • CL / Changelist — 本來源中只是 Google 術語，對應外部常見 PR / change / patch；目前併入 Code-Review 術語段，不獨立建頁。
  • Nit — 是 review comment severity label，不獨立建頁；併入 Code-Review。
  • LGTM — 本來源沒有展開；併入 Code-Review 備註，待未來 PR etiquette / review tooling 來源再評估。

觀察清單同步：

  • 更新 MOC-工程 / MOC-工程紀律 候選進度：本來源讓工程紀律 cluster 達到來源面 4/5、概念面 5+，但仍未達 MOC 建頁門檻。
  • 新增待 ingest 外部資源：Google Engineering Practices Code Review Guidelines（官方原始文件）。本次以 Ryan Yang 中文整理為主來源，只讀官方文件校準重點，尚未將官方文件本身作完整來源頁。
  • 更新 降低防禦反應 / 建設性回饋 umbrella 候選：code review comment 明確提供「對事不對人、說明原因、標註 severity、讓 developer 有空間學習」的工程場景版本，進度由 4 對位增至 5 對位。

vault 定位元命題：

本來源把 vault 既有「技術工作流」cluster 從 GitHub工作流 / Pull-Request 的工具層推進到「工程品質治理」層：PR 只是介面，真正決定 codebase 是否長期健康的是 reviewer 如何權衡「品質 vs 速度」、如何把 style / tests / documentation / complexity / context 納入同一套判準，以及如何用不觸發防禦的方式讓 developer 願意改。這也把 AI輔助開發 的安全網從「branch + diff + PR」擴展為「agent 產物也必須通過 human code review 的工程治理判準」。

原文（可選）

以下全文由使用者於 2026-05-06 貼入；Medium 頁面本身標示 member-only，直接抓取只可見開頭與後設資料。

我們常常會有很多的機會需要 Code review，那你有沒有想過怎樣才是好的 Code review 呢？看以前主管怎麼做就怎麼做？還是只是照著個人的直覺想法下去進行呢？

就在最近，Google 釋出了內部如何進行 Code Review 的文件。對於 Google 來說，幾乎所有大家在使用的語言 Google 也都有在用，而這份文件就是把這十幾年下來的經驗濃縮並且公諸於世，希望能夠給大家做個參考甚至直接就拿來當作準則。本文將其內文整理成這篇文章，那就讓我們一起來讓 Google 教你 Code Review 吧！

(註: 以下會提到的 CL 指得是 Change list，也就是 Developer 想要 Submit 進 Version control 並且被 Review 的東西)

Code review 的基本概念

Code review 的本質就是要讓我們的 codebase 能夠維持一定的健康度並且是不斷地進步的。基本上，Developer 要做的就是要能夠 Submit 可以讓 Codebase 進步的 Code，不管是功能還是重構等等。而 Reviewer 也要避免一次給出許多很難去做到的建議，因為這會抑制未來 Developer 想要持續改進的心。Reviewer 的心態應該是要做好把關，不讓整個 codebase 因為一些時間壓力而讓不好的 CL 進到 codebase 使之腐敗。注意的是，Approval 一個 CL 的基本原則是，只要確定這次的 CL 是可以讓 Codebase 有所進步，不管是功能上，可維護性，可讀性等等，就應該給出 Approval，而不是耗時追求完美，因為只有更好的 Code，而沒有完美的 Code。

在留 Comment 的時候，Reviewer 會針對必要的改善給出建議，不過如果當有些 Comment 並不是那麼重要的時候，就可以在 Comment 的前面加上 Nit: 讓 Developer 了解這些 Comment 是可以先看看就好。屬於 Nit: 的 Comment 還有像是有的時候，Reviewer 有一些新的 Knowledge 要 Share 給 Developer，也可以留下 Comment (加上 Nit:)，雖然這看似與這次的改動沒有全然相關，但也許這樣的 Knowledge 對於日後 Codebase 的進步是有幫助的，那麼 Reviewer 就應該透過這個機會，來去教育 Developer。

Code Review 的原則

  1. 要能給出技術上的建議，而不是個人偏好。
  2. 假使公司有規定 Coding style，那應該要有共同一致的參考文件。假使沒有，那通常就是直接順應 Developer 。
  3. 關於軟體設計的部分，必須根據一些軟體設計的基本原則去權衡考量，而不是因為個人偏好就想要改動 Developer 原先的做法。假使 Developer 可以展示各種做法結果都是可行的話，那就應該聽從 Developer 的選擇。不然就是 Follow 軟體設計的基本原則。
  4. 假使有些部分並沒有規則可以參考的時候，Reviewer 在確定不會讓 Codebase 變糟的情況下，應該要求讓 Developer 去 Follow 目前 Codebase 原來的做法以保持一致性。

假使今天 Reviewer 和 Developer 一直沒有辦法達成共識呢？最忌諱的就是讓這個 CL 一直躺在那邊，也避免一直在 Comment 的地方來回，應該進一步開啟一個 face to face 的會談，好好溝通彼此的想法，或是開一個更大的會議，請 maintainer 或是技術主管一起來看看怎麼樣做最好。

Code Review 實際上要看些什麼呢

  1. Design:這是最重要的部分，也就是這次CL 整體的設計。這次 CL 的 code 是否 make sense？和其他的 Component 還是 Library 是否整合得宜？在這個時間點是否要加入這一個改動？這部分是用 Overall 或是 High level 的角度來看。

  2. Functionality:從功能面來看是否有達到原來的目標呢？對未來的使用者是否帶來益處呢？這裡未來的使用者可能是 End user 或是未來會碰這塊的其他 Developer。 Reviewer 在這裡也要扮演 User 的角色去思考問題，例如是否有些 Edge case 等等。如果 Reviewer 有時間的話，可以不只是閱讀而已，還應該親自進行測試，或是由 Developer 進行演示。(理論上 Developer 在開發的時候就應該要有一些測試來驗證) 有些很難測試的部分，例如 Deadlocks，race conditions 等等，就必須要好好思考是否有這樣的問題存在。當然更好的方式是，不要採用可能會產生 Deadlocks，race conditions 的模型來去撰寫程式。

  3. Complexity:這一段 Code 是否寫得過於複雜？太複雜帶來的問題是，可讀性變差，以及在使用或是修改的時候容易引入 Bug。另外就是不要過度工程 (over-engineering)，也就是有些代碼並不是為了解決現在的問題或功能，可能是目前系統不需要的功能，也可能是 Developer 覺得為了通用而提早設計了一些介面。但現在的通用並不代表未來的通用。

    我認為應該是讓 Code 保有彈性和可讀性，在未來可以好做修改，但不要去預設未來一定某個時刻就會發生某事而提早設計，很有可能不但用不到，又會讓當前的焦點被模糊。

  4. Tests:在合理的時間允許下，Reviewer 應該要要求寫測試，最基本的就是 Unit test，再來可能有 Integration test，end-to-end test 等等。Reviewer 也要確保這些測試是有意義的，並且是正確的。很多人常常覺得那我就寫很多測試，然後可能有很多其實意義不大，只是為了衝 Coverage rate。但很重要的觀念是，Tests 其實也應該被視為 Production 的一部分，是用來保護 Codebase，所以也要具備 readability，maintainable，以及不要搞得太複雜。因為功能上的 Code 本身在未來可能會被修改，就可能導致 Tests 也必須要跟著修改，所以 Tests 跟功能上的 Code 一樣也是要 based 一些基本的 Coding 原則，千萬不要只是為了寫 Tests 而寫 Tests。

  5. Naming:好的 Naming 要能夠清楚表達這是什麼，或者這是在做什麼，以維持可讀性。

  6. Comment:我們常常看到很多人在寫 Comment 的時候，寫下的是這段 Code 在做什麼事，但如果 Code 寫的好，理論上看 Code 就應該知道這段 Code 在幹嘛，而且如果 Comment 沒寫好，反而有時候還會誤導。我們的 Comment 應該要寫的是，這段 Code 為什麼存在，主要是為了達到什麼效果，我認為這是很重要的。有時候因為當時的時空背景，而有了這段 Code，但當後來在看的時候，如果不知道當時原因，可能就會納悶為什麼這邊要有這段，假使真的是有他的必要性，但你卻因為不知道而修改了，就可能導致某些 Bug 在未來就出現了。

  7. Style:如果公司有 Style guide 就應該要 follow。假設有一些不在 Style guide，Reviewer 又覺得是好的，就如同先前所說應該要加上 Nit: ，避免讓 Style 的問題，卡住了這個 CL 的 Approval。假設有一些 Style 的問題必須要讓 Developer 去修改，應該要獨立成一個 CL，以跟其他功能面的 CL 作為分別，避免混在一起在未來例如需要 Rollback 的時候變得複雜。

  8. Documentation:如果我們有為 Codebase 撰寫文件，這裡也要注意這次的 CL 是否也要同步去修改文件的部分以同步。

  9. Every line:要能夠理解每行 Code，不要覺得哪些 function 或 class 應該是 OK 的就略過。假設你無法理解，就讓 Developer 來為你說明，這同時也是幫助未來其他人也能夠理解。如果理解了，但對於有些複雜的問題沒有信心做 Review 的話，應該要尋求在這方面有經驗的人來一起幫忙 Review。

  10. Context:在 Code review 的時候，Reviewer 常常只會看到 Diff 的部分，而我們應該要連同上下文，例如觀看整個 Function，來審視這次的 CL，即使改動的部分很少也是要通盤考慮，避免反而增加了系統的複雜度等等。

  11. Good things:Code review 不該只是找錯誤，有時候如果 Developer 寫得好，也可以留下 Comment 來讚美，因為每次的 Review，其實都可以當作一個 Mentoring 的機會，這也會帶來正面的助益。

我覺得這邊很好的觀念是，要把 Review 當作是檢視是否能夠讓整個 Codebase 得到進步，要判斷這點，就要注意上下文，並且不要略過一些你覺得不會出錯的地方。並且把每次 Review 當作是 Mentoring 的機會，做得好的部分就應該要讓 Developer 知道。

看到這邊覺得還不錯的可以登入按讚支持我繼續寫下去～

Review 的步驟

  1. Take a broad view of the change:這裡是先從 Overall 的角度來觀看這次的 CL，假設有些改動根本不應該發生，應該立即地向 Developer 提出，並給予解釋及應該要做什麼的指示。但這裡要注意的是表達的方式，我們還是要尊重到 Developer，例如我們應該說 “感謝你認真思考並且努力去修改 XXX 的部分，只是因為 XXX 之後可能也不會再用，所以應該要再麻煩你改成針對 YYY 去修改。” 至於有時候會發生這件事情可能是因為前期溝通沒有講好，導致都改完了才發現做白工，這時候應該要去檢討的是，前期的過程該怎麼樣改善。
  2. Examine the main parts of the CL:有時候一次的 CL 很多檔案的改動時，我們應該找出最多邏輯改動的那個檔案，當作是主要修改的部分，這能夠幫助我們在之後觀看其他檔案的小改動時，更能夠知道為什麼會有這些的改動。但如果實在不知道哪個檔案是主要的，就要詢問 Developer，或者是把太大的 CL 改成小一點的 CL 們。如果當你在看主檔案就發現設計的一些問題，就應該立即回給 Developer，因為這時候看小檔案的改動就沒有什麼意義。Developer 假使能夠儘早知道主設計的問題時，就能夠及早修改，避免本來在 Review 的期間，Developer 會 based on 錯誤的設計繼續開發。
  3. Look through the rest of the CL in an appropriate sequence:當確定主要的部分已經沒問題了，就把剩下的部分看完。如果有測試的話，就先從測試開始看，這樣可以先在內心有個想法，再來看 Code 本身會比較有效率。

Code review 的速度

我們先來看看假設 Code review 太慢會怎樣。第一個當然是整個團隊的開發速度會被拖累，後續的進度也會卡住。第二個是如果 Reviewer 幾天才回，每次回又都是要 Developer 做大改動，Developer 的心情應該不會太好。第三是假使 Review 很慢，又有時程壓力的情況下，就可能導致 Developer 為了被 Review，而提早交出一個相對不是那麼好的 CL。

所以應該要多快呢？假設你手邊不是正需要很專注做某件事情的話，應該要在收到 Request 的時候，盡快進行 Review，最遲也不要超過一個工作天。不過當然如果你在專注某個 Task，應該不要被打斷，因為通常對 Developer 來說，被打斷之後要重新回到開發時的平穩狀態並不是一下子的事。所以還是要找個斷點再做 Review ，例如午飯回來等等。

這裡我們所要求的速度，其實不是指 Review 完全部的速度，而是回應的速度。即使我們發覺需要一段時間來 Review 完全部，也應該在有一些意見的時候就先回覆。假設真的沒有時間，也應該在斷點的時候，和 Developer 說明大概何時會進行 Review，先給一些 Broad view 的想法，而不會讓 Developer 有等待和焦慮的感覺。假如今天 CL 真的很大呢？那應該要求 Developer 切成小 CL 們，雖然會花一點點 Developer 的時間，但是卻能夠大大幫助 Reviewer 能夠更有效率去幫忙 Review，也能夠進而讓 Developer 不會在那空等，而是能夠儘快有下一步的事情能夠去完成。

假如一切都順利的話，經過幾輪這樣的實踐後，Review 的速度應該會越來越改善，不管是從 Developer 方還是 Review 方，都漸漸了解到如何在一開始就做到讓 Review 更加快速。不過切記的是，雖然速度很重要，但千萬不要到最後速度提升了，但品質卻下降了，還是要遵循上面所提到的那些 Code review 的原則以及需要審視的部分。

如何撰寫 Comment

好的 Comment 可以有幾個要素：1. 友善與尊重的語氣。對事不對人。例如不要直接問說為什麼你要這麼做，而是提出說這麼做有什麼樣不好的地方應該要怎麼做。

  1. 要充分給予說明。可以的話盡量提出會給這些建議的原因，例如是參考了什麼 Good practices。

  2. 在直接點出問題給出答案以及讓 Developer 自己做一些思考和決定之間取得平衡。記得把 Code 改好是 Developer 的責任而非 Reviewer 的。Reviewer 並不用為 Developer 想出整個 Solution 或是幫忙寫 Code。Reviewer 可以做的是點出問題，並且給予方向，這樣子 Developer 才能夠去學習並內化。不過有時候非不得已， Reviewer 可能還是要提供更多的細節或是一小段的程式，因為一個 CL 的主要目的還是要改善整個 Codebase，次者的目的才是讓 Developer 有所成長。

  3. 鼓勵 Developer 把 Code 簡化或是留下 Comment 而不是花很多時間解釋複雜的東西給你聽。

如何面對 Developer 的反饋

Developer 有時候並無法同意 Reviewer 的意見，這時候 Reviewer 應該要好好審視 Developer 的回應，因為 Developer 才是最接近 Code 的人，假使他的解釋你認同了，並且認定並不會對 Codebase 有所損害時，就應該承認 Developer 是對的。如果 Reviewer 相信自己的部分是對的，那就應該再繼續跟 Developer 解釋。但注意過程必須保持尊重，要讓 Developer 了解到他們的聲音是有被聽見的，即使你並不同意。假使你有好好照著好 Comment 的準則去寫，那麼就不應該擔心這會讓 Developer 感到受挫，因為這是能夠讓他們進步的。

有時候 Developer 對於你的嚴格會有所抱怨，但如果這對他們真的是好的，這些抱怨在未來就會漸漸消失，而這些 Developer 反而可能會對你有所感激，並且成為你的支持者。不過為了讓短期的抱怨降到最小，應該要參考上面所提到的，關於提升 Review 速度的部分，用那些方法來讓 Developer 感到你的友善以及尊重。

有些 Developer 會說，有些東西我會留著下次改，因為他們想要趕快這次的 Review 結束並且交差。但通常現在不改，以後大概也不會改了，因為新的事情會一直來。所以還是要堅持讓 Developer 在這一次就改好才能進 Codebase，不然往往最後整個 Codebase 的衰敗就是因為這些累積。假設這次的改動引發了一些目前無法解決的問題，那麼就應該先記成 Bug，並 Assign 給 Developer 自己，且 Reference 到這次的改動片段，加上 TODO 的註解來讓自己不會在之後忘了回頭來看這些問題。

我現在就是很急!

假如現在真的很急很急要被 Approved 該怎麼辦？那我們就要先來審視是否真的是緊急狀況。緊急狀況應該要是範圍很小但很重要的改動，例如安全性的問題，影響 User 嚴重的問題等等。Reviewer 也要把這個 CL 的 Priority 放到最優先，並且盡快針對正確性進行 Review。如果可以的話，之後應該要回頭再好好看過一遍，並以正常的方式再去 Review 一次。

那麼有哪些是看起來很急其實並不急的呢？例如想要提早一週完成並面世 (除非是真的一定要，不然會喪失市場之類的)；Developer 想要趕快結束一個長期的開發；想趁週末來臨之前趕快完成 Review 等等。

結語

我覺得 Google 的這個 Guide，應該是把所有的情境都給考慮進去了。永遠記得 Code review 的目的是為了讓 Codebase 更好，為了更好，就要注意哪些部分是必須要去審視的。實際運作的時候，就要考慮速度並且同時兼顧品質。最後就是，因為 Code review 其實也是 Reviewer 和 Developer 的對話，如何讓雙方都在舒服的情況下，去做到雙贏，這也是很重要的課題。如果上述的觀念我們都能記在心中並且去實踐，相信 Code review 就不再是一件被認為是痛苦且耗時的事情囉！

Ref: https://google.github.io/eng-practices/review/reviewer/

反向連結