google-eng-practices

Google 工程實踐 — Code Review 指南

基於 Google Engineering Practices 整理，涵蓋 reviewer 與 author 兩個角色的最佳實踐。

自動化行為（必須遵守）

以下行為在對應場景中自動觸發，不需要使用者手動要求：

寫程式碼時 — 自動套用小 CL 原則

• 每個變更只做一件事
• 重構與功能變更分開
• 測試與對應的程式碼放在同一個變更中
• 如果發現單一變更超過 ~100 行，主動拆分

建立 PR 時 — 自動產生高品質描述

• 標題：祈使句簡述做了什麼
• 本文：說明為什麼、背景、限制
• 含 Test Plan 區塊
• 不及格範例：「Fix bug」「Add patch」「Phase 1」

審查程式碼時 — 自動套用 Reviewer 標準

面向	重點
設計	架構合理？功能放對位置？
功能	符合意圖？邊界情況？並行安全？
複雜度	讀者能快速理解？避免過度工程
測試	正確、有意義、程式壞了會失敗
命名	清楚傳達意圖，不過長
註解	說明「為什麼」而非「做什麼」
風格	遵循 style guide，非必要標「Nit:」
文件	影響使用方式時更新文件

審查步驟： 先看全貌（CL 是否該做）→ 看主要邏輯 → 逐行看其餘檔案

術語

CL（Changelist）： 一個獨立的、可審查的變更單位，等同於 GitHub 的 pull request。

LGTM（Looks Good to Me）： Reviewer 核准 CL 時的用語。

核心原則

審查的黃金準則： 只要 CL 確實改善了整體程式碼健康度，就應該核准，即使它不完美。不存在完美的程式碼，只有更好的程式碼。

技術事實優先於個人偏好。 當多種方案都有充分依據時，尊重作者的選擇。

與 atomic-conventional-commits 的協作

兩個 skill 各司其職，自動配合：

時機	atomic-conventional-commits	google-eng-practices
寫程式碼時	完成邏輯變更 → 立即 commit	確保變更範圍小且自洽
commit 時	格式化 commit message	—
建立 PR 時	—	產生高品質 PR 描述
Code Review 時	—	套用 Reviewer 審查標準

留言原則： 對事不對人、說明理由、標示嚴重程度（Nit/Optional/FYI）、鼓勵好的做法

詳細 Reviewer 指南：見 references/reviewer-guide.md 詳細 Author 指南：見 references/author-guide.md

緊急情況

符合緊急條件： 重大上線回滾、影響使用者的正式環境錯誤、重大安全漏洞、法律問題

不算緊急： 想在本週而非下週上線、開發者想結束長期工作、reviewer 不在線、經理的軟性截止日

緊急 CL 優先審查速度和正確性，但事後必須進行完整審查。