認知負擔 Code Review 工具

核心理念

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

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

審查維度

1. 變數狀態追蹤

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

2. 呼叫層級追蹤

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

3. 命名品質

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

btn

mgr

button

manager

data

info

userData

bookInfo

handle()

process()

validateInput()

calculateTotal()

getTheUserDataFromDatabase

fetchUser

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