# 你真的知道Code Review到底在幹麻嗎？如何高效發起、提出建設性意見，並建立健康的團隊文化

## 📌 I. 前言：Code Review 的真正價值

許多人以為 Code Review (CR) 的目的只是「抓 Bug」。

其實那只是副產品。一個成熟團隊進行 Code Review 的**本質價值**在於：

* **知識共享與傳承：** 讓第二位甚至第三位工程師了解程式碼的意圖與設計背景。
* **穩定地維持品質標準：** 讓新加入的程式碼符合團隊的一致性哲學，例如模組化、SRP、命名、錯誤處理方式等。
* **降低技術債：** 避免不穩定或耦合過高的設計在合併後擴散。

**結論：** Code Review 是團隊在「一起寫同一個系統」，而不是「各寫各的再拼起來」的關鍵機制。

---

## 🚀 II. 發起者的責任：讓審查流程高效運轉

送出 PR/MR 的人必須確保「輸入品質良好」。這是對 Reviewer 最基本的尊重，也是成熟工程師的習慣。

### 1. 環境設定：確認風格規範 (Linter / Formatter)

風格問題不應該由人類來糾正。在開始寫 Code 或提交 PR 前，務必確認：

* 專案使用什麼 Linter？（例如 ESLint、Pylint）
* 使用什麼 Formatter？（例如 Prettier、Black）
* 是否有 pre-commit hook？

**專業習慣：** 讓你的編輯器和本地工具自動處理風格細節，確保程式碼通過機器檢查後，再交付給真人審核。

### 2. 小而專注的提交（Small & Focused PR）

「大型 PR = Reviewer 想逃走」這條在所有公司都是真理。越小的 PR，越快被審查，也越容易被理解。

* **原則：** 一次只做一件事，**專注於單一職責 (SRP)**。
* **技巧：** 不要把重構＋新功能＋修 Bug 全塞在同一個 PR 中。
* **加分項：** 有 UI 的變更，盡可能附上截圖或小影片。

### 3. 詮釋 Context：讓 Reviewer 秒懂你要做什麼

Reviewer 不是讀心術專家。你必須在 PR 描述中，清楚地寫下設計意圖。

| 必填內容 | 目的與範例 |
| :--- | :--- |
| **問題背景** | 連結任務單、說明這個 PR 解決了什麼問題。 |
| **設計說明** | 簡述設計取捨，例如：「為了降低耦合，我引入了策略模式。」 |
| **核心變更** | 指定 Reviewer 應從哪些檔案開始看，或跳過哪些純粹是風格修改的檔案。 |

---

## 🔍 III. 審查者的職責：如何提出建設性意見

Reviewer 的角色不是裁判，而是共創者。你不是在挑錯，而是在幫忙做「設計驗證」。

### 1. 審查優先級：從最高的風險開始看

你必須將注意力放在高價值的審查點上：

| 優先級 | 檢查目標 | 說明 |
| :--- | :--- | :--- |
| **高** | **架構、設計與 SRP** | 是否違反單一職責？模組邊界是否清晰？這個變動會不會在系統其他地方製造副作用？ |
| **中高** | **穩定性與錯誤處理** | 參數輸入是否有 **Null Pointer** 疑慮？是否考慮外部 API 錯誤、逾時？是否有適當的 Log 紀錄？ |
| **中** | **業務邏輯正確性** | 是否考慮了邊界條件 (Edge Cases)？核心邏輯是否有誤？ |
| **低** | **可讀性與命名** | 命名是否清晰？這個級別的問題通常應該由 Linter 處理。 |

> **總結：** 先問「設計」對不對，再問「寫法」漂亮不漂亮。

### 2. 語氣技巧：對事不對人

CR 應該是一場設計交流，而不是辯論會。建議使用以下語氣來建立心理安全感：

* **提問式：** 「為什麼這邊選用 Dictionary？是基於效能考量嗎？」（鼓勵思考）
* **建議式：** 「我建議把這段抽成獨立方法，這樣可以更清晰地分離職責。」（而非「你寫錯了，重寫」）
* **讚美平衡：** 不要只挑錯誤，同時讚美優秀的設計和清晰的命名。

---

## 🌱 IV. 如何在團隊建立健康的 Code Review 文化

這段是讓您文章更像一篇「指南」而不是純技巧文。

### 1. 把機器能做的自動化（減少人為摩擦）

演算法未必能取代工程師，但至少能取代「盯縮排」這件事。

* **工具清單：** Linter、Formatter、Type checking、CI/CD 中的單元測試。
* **目的：** 將 Reviewer 的精力完全釋放到高優先級的「設計」檢查上。

### 2. 訂定基本規範（避免自由心證）

沒有規範，CR 文化只會靠運氣。每個團隊至少該定義：

* PR 大小建議（例如：理想上 ≤ 300 行）。
* 審查時間 SLA（例如：24 小時內要有初步回應）。
* 哪些檔案（例如：`service` 或 `domain` 層）需要附帶單元測試。

### 3. 建立心理安全感（CR 最容易被忽略的地方）

**程式可修，信任難補。** 避免：

* 公開羞辱式評論或不友善的語氣。
* 不聽解釋的「我說了算」。
* Reviewer 太兇導致新人怕提 PR。

好的 CR 文化會讓新人說：「我放心把 PR 交給你們。」

---

## 🎒 V. 新手跨越恐懼期：第一次 Code Review 的心態與準備

這段最能幫助新人跨過恐懼期。

### 1. 心態：這不是考試，也不是在打分數

CR 是分享寫法、找盲點、建立一致性、一起把系統寫得更可維護的過程。你的 Reviewer 願意花時間，就是重視你。

### 2. 提交前自查清單

* Linter 無錯。
* 重要邏輯自己跑過一次。
* Git Diff 自審一次，確認變動是合理的。
* 說明清楚 PR 的目的，且 PR 大小合理。

### 3. 如何回應 Reviewer 價值最大？

* **不要防禦性回覆：** Reviewer 是在質疑 Code，不是質疑你。請說明你的設計理由，而不是爭辯對錯。
* **不懂就問，不要硬撐：** 「可以補充為什麼這邊需要這樣做嗎？」這是團隊最喜歡聽到的句子。
* **遇到複雜討論，開會最快：** 打字吵三天，不如開個 15 分鐘視訊會議，能立刻解決誤會和設計分歧。

---

## ✅ VI. 總結：Code Review 是團隊智慧的放大器

Code Review 不是審判，也不是技巧比賽。它是一場「讓系統更好」與「讓工程師更成熟」的循環。

當 CR 做得好時：

* 新人變強
* 資深不用救火
* 系統品質變穩
* 技術債自然減少

Code Review 是成熟工程文化最關鍵的基石之一。