majiayu000 認知負擔 Code Review 工具
核心理念
好的程式碼不需要讀者額外的認知努力就能理解
Code Review 的目標不只是找出錯誤，更重要的是確保程式碼對未來的閱讀者友善。
審查維度
1. 變數狀態追蹤
檢查問題：這段程式碼需要閱讀者同時記住幾個變數的狀態？
| 變數數 | 評估 | 建議 |
|---|---|---|
| 1-3 | 優良 | 維持 |
| 4-5 | 可接受 | 考慮提取函式 |
| > 5 | 需重構 | 拆分為更小的函式 |
2. 呼叫層級追蹤
檢查問題：理解這段程式碼需要追蹤幾層呼叫？
| 層級 | 評估 | 建議 |
|---|---|---|
| 1-2 | 優良 | 維持 |
| 3 | 可接受 | 考慮扁平化 |
| > 3 | 需重構 | 提取中間函式或使用組合 |
3. 命名品質
檢查問題：不看實作，能從名稱理解意圖嗎？
| 問題類型 | 範例 | 改善建議 |
|---|---|---|
| 縮寫不明 | btn, mgr |
button, manager |
| 含義模糊 | data, info |
具體化：userData, bookInfo |
| 動作不清 | handle(), process() |
validateInput(), calculateTotal() |
| 過長冗餘 | getTheUserDataFromDatabase |
fetchUser |
4. 條件分支
檢查問題：需要考慮幾條執行路徑？
| 分支數 | 評估 | 建議 |
|---|---|---|
| 1-2 | 優良 | 維持 |
| 3-4 | 可接受 | 考慮策略模式或早期返回 |
| > 4 | 需重構 | 使用策略模式或狀態模式 |
5. 函式長度
檢查問題：這個函式做了幾件事？
| 行數 | 評估 | 建議 |
|---|---|---|
| 5-10 | 優良 | 維持 |
| 11-20 | 可接受 | 考慮拆分 |
| > 20 | 需重構 | 必須拆分 |
6. 參數數量
檢查問題：呼叫者需要記住幾個參數的順序和意義？
| 參數數 | 評估 | 建議 |
|---|---|---|
| 0-2 | 優良 | 維持 |
| 3 | 可接受 | 考慮參數物件 |
| > 3 | 需重構 | 使用參數物件或建造者模式 |
審查清單
函式層級
- 函式長度 <= 20 行
- 參數數量 <= 3
- 巢狀深度 <= 3
- 區域變數數 < 5
- 函式名稱是動詞片語
- 函式只做一件事
類別層級
- 類別方法數 <= 12
- 公開方法數 <= 5
- 類別依賴數 <= 5
- 類別名稱是名詞
- 單一責任明確
命名層級
- 無縮寫或僅使用業界通用縮寫
- 變數名稱是名詞或名詞片語
- 布林變數是 is/has/can 開頭
- 常數名稱全大寫底線分隔
- 不使用 data/info/value 等模糊詞
認知負擔熱點識別
常見熱點
| 熱點類型 | 識別方法 | 影響 |
|---|---|---|
| 長函式 | > 20 行 | 難以一次理解 |
| 深巢狀 | > 3 層縮排 | 上下文難追蹤 |
| 多參數 | > 3 個參數 | 呼叫時容易出錯 |
| 副作用 | 修改外部狀態 | 行為不可預測 |
| 隱藏依賴 | 內部 new 物件 | 難以測試和理解 |
熱點優先級
| 優先級 | 類型 | 處理方式 |
|---|---|---|
| P0 | 副作用 | 立即修復 |
| P1 | 深巢狀 | 本次 PR 修復 |
| P2 | 長函式 | 建立技術債 Ticket |
| P3 | 多參數 | 視情況處理 |
審查報告格式
## 認知負擔 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 行
常見原因：
- 混合多個責任
- 缺乏抽象層
改善方法：
- 識別獨立的邏輯區塊
- 提取為私有方法
- 命名要說明「做什麼」
模式 2：深層巢狀
識別：超過 3 層縮排
常見原因：
- 多層條件判斷
- 迴圈內的條件
改善方法：
- 使用早期返回（Guard Clause）
- 提取內層邏輯為函式
- 考慮策略模式
模式 3：模糊命名
識別：使用 data, info, value, result 等詞
常見原因：
- 趕時間隨意命名
- 不確定用途
改善方法：
- 問「這個變數存放什麼？」
- 用具體名詞回答
- 加入領域詞彙
模式 4：隱藏副作用
識別：函式名稱是查詢，但會修改狀態
常見原因：
- 「順便」修改狀態
- 缺乏命令-查詢分離
改善方法：
- 分離查詢和命令
- 命名反映副作用
- 減少副作用範圍
相關文件
- 認知負擔量化標準
- 認知負擔設計方法論
- 自然語言程式設計方法論
- 程式碼品質門檻方法論
Last Updated: 2026-01-23 Version: 1.0.0