認知負擔 Code Review 工具

核心理念

好的程式碼不需要讀者額外的認知努力就能理解

Code Review 的目標不只是找出錯誤，更重要的是確保程式碼對未來的閱讀者友善。

審查維度

1. 變數狀態追蹤

檢查問題：這段程式碼需要閱讀者同時記住幾個變數的狀態？

2. 呼叫層級追蹤

檢查問題：理解這段程式碼需要追蹤幾層呼叫？

3. 命名品質

檢查問題：不看實作，能從名稱理解意圖嗎？

4. 條件分支

檢查問題：需要考慮幾條執行路徑？

5. 函式長度

檢查問題：這個函式做了幾件事？

6. 參數數量

檢查問題：呼叫者需要記住幾個參數的順序和意義？

審查清單

函式層級

• 函式長度 <= 20 行
• 參數數量 <= 3
• 巢狀深度 <= 3
• 區域變數數 < 5
• 函式名稱是動詞片語
• 函式只做一件事

類別層級

• 類別方法數 <= 12
• 公開方法數 <= 5
• 類別依賴數 <= 5
• 類別名稱是名詞
• 單一責任明確

命名層級

• 無縮寫或僅使用業界通用縮寫
• 變數名稱是名詞或名詞片語
• 布林變數是 is/has/can 開頭
• 常數名稱全大寫底線分隔
• 不使用 data/info/value 等模糊詞

認知負擔熱點識別

常見熱點

熱點優先級

審查報告格式

## 認知負擔 Code Review 報告

### 檔案: {檔案路徑}

### 整體評估

| 維度 | 評分 | 說明 |
|------|------|------|
| 變數管理 | {1-5} | {說明} |
| 呼叫層級 | {1-5} | {說明} |
| 命名品質 | {1-5} | {說明} |
| 函式設計 | {1-5} | {說明} |
| **總評** | **{1-5}** | **{說明}** |

### 熱點清單

| 行號 | 類型 | 問題 | 建議 | 優先級 |
|------|------|------|------|--------|
| {行} | {類型} | {問題} | {建議} | {P0-P3} |

### 命名問題

| 原名 | 問題 | 建議名稱 |
|------|------|---------|
| {原名} | {問題} | {建議} |

### 重構建議

1. **{建議標題}**
   - 位置: {行號範圍}
   - 問題: {問題描述}
   - 方案: {重構方案}
   - 預期效果: {效果描述}

### 優點

- {優點1}
- {優點2}

### 結論

- **可以合併**: {是/否/需修改後}
- **必須修改**: {列表}
- **建議修改**: {列表}

使用方式

審查單一檔案

/cognitive-review {檔案路徑}

審查 PR 變更

/cognitive-review pr {PR 編號}

快速掃描

/cognitive-review scan {目錄}

常見問題模式

模式 1：函式過長

識別：函式超過 20 行

常見原因：

• 混合多個責任
• 缺乏抽象層

改善方法：

1. 識別獨立的邏輯區塊
2. 提取為私有方法
3. 命名要說明「做什麼」

模式 2：深層巢狀

識別：超過 3 層縮排

常見原因：

• 多層條件判斷
• 迴圈內的條件

改善方法：

1. 使用早期返回（Guard Clause）
2. 提取內層邏輯為函式
3. 考慮策略模式

模式 3：模糊命名

識別：使用 data, info, value, result 等詞

常見原因：

• 趕時間隨意命名
• 不確定用途

改善方法：

1. 問「這個變數存放什麼？」
2. 用具體名詞回答
3. 加入領域詞彙

模式 4：隱藏副作用

識別：函式名稱是查詢，但會修改狀態

常見原因：

• 「順便」修改狀態
• 缺乏命令-查詢分離

改善方法：

1. 分離查詢和命令
2. 命名反映副作用
3. 減少副作用範圍

相關文件

• 認知負擔量化標準
• 認知負擔設計方法論
• 自然語言程式設計方法論
• 程式碼品質門檻方法論

Last Updated: 2026-01-23 Version: 1.0.0