majiayu000 認知負擔評估工具
核心理念
所有程式碼設計原則的終極目標：降低閱讀者的認知負擔
認知負擔是指閱讀者在理解程式碼時需要同時記住的資訊量。當認知負擔超過人類工作記憶的容量（約 7 個項目），理解和維護程式碼就會變得困難。
量化標準快速參考
任務複雜度閾值
| 指標 | 低複雜度 | 中複雜度 | 高複雜度（需拆分） |
|---|---|---|---|
| 變數狀態數 | 1-3 | 4-5 | > 5 |
| 修改檔案數 | 1-3 | 4-5 | > 5 |
| 架構層級數 | 1 | 2 | > 2 |
| 依賴模組數 | 0-1 | 2-3 | > 3 |
| 呼叫追蹤層 | 1-2 | 3 | > 3 |
代理人升級閾值
| 指標 | 閾值 | 行動 |
|---|---|---|
| 需追蹤概念數 | > 7 | 升級到 PM |
| 無法 5 分鐘理解 | 是 | 升級到 PM |
| 跨 2+ 架構層 | 是 | 請求拆分或協作 |
並行派發判斷
| 條件 | 可並行 | 需序列 |
|---|---|---|
| 架構層級 | 同一層 | 跨層 |
| 邏輯依賴 | 無 | 有 |
| 操作類型 | 重命名/格式化 | 設計變更 |
認知負擔的來源
1. 變數狀態追蹤
每個變數都是閱讀者需要「記住」的項目：
| 情況 | 認知負擔 | 建議 |
|---|---|---|
| 變數數 <= 3 | 低 | 維持 |
| 變數數 4-5 | 中 | 考慮重構 |
| 變數數 > 5 | 高 | 必須拆分 |
2. 呼叫層級追蹤
追蹤呼叫鏈需要「堆疊」記憶：
| 層級 | 認知負擔 | 建議 |
|---|---|---|
| 1-2 層 | 低 | 維持 |
| 3 層 | 中 | 考慮扁平化 |
| > 3 層 | 高 | 必須重構 |
3. 命名品質
不佳的命名增加「翻譯」負擔：
| 問題 | 範例 | 解決 |
|---|---|---|
| 縮寫不明 | btn, mgr, idx |
button, manager, index |
| 含義模糊 | data, info, value |
具體化：userData, bookInfo |
| 型別前綴 | strName, intCount |
直接用 name, count |
4. 條件分支複雜度
每個分支都是需要考慮的「路徑」：
| 分支數 | 認知負擔 | 建議 |
|---|---|---|
| 1-2 | 低 | 維持 |
| 3-4 | 中 | 考慮策略模式 |
| > 4 | 高 | 必須重構 |
降低認知負擔的原則
原則 1：單一責任
一個函式只做一件事，讓讀者只需理解一個概念
檢查問題：「這個函式做了幾件事？」
原則 2：自說明命名
名稱本身就是文件，讓讀者不需要額外資訊
檢查問題：「不看實作，能從名稱理解功能嗎？」
原則 3：避免副作用
函式的行為應該可預測，讓讀者不需要追蹤隱藏狀態
檢查問題：「這個函式有沒有修改輸入以外的東西？」
原則 4：扁平化結構
減少巢狀，讓讀者不需要追蹤深層上下文
檢查問題：「最深的巢狀層級是多少？（應 <= 3）」
原則 5：資訊就近原則
相關的資訊應該放在一起，讓讀者不需要跳轉尋找
檢查問題：「理解這段程式碼需要跳到幾個地方？」
自我檢查清單
任務開始前
- 我需要同時記住多少個概念？（應 < 7）
- 我需要閱讀多少個檔案才能完成？（應 < 5）
- 我能用一句話說明這個任務嗎？
- 5 分鐘後我還記得任務目標嗎？
程式碼撰寫時
- 這個函式需要追蹤幾個變數？（應 < 5）
- 讀者能在當下理解這段程式碼嗎？
- 函式名稱說明「做什麼」而非「怎麼做」？
- 巢狀層級是否超過 3 層？
Code Review 時
- 新程式碼是否增加了模組的複雜度？
- 有沒有更簡單的方式達成同樣目的？
- 命名是否清晰自說明？
- 是否需要額外註解才能理解？（應該不需要）
與其他方法論的關係
| 方法論 | 認知負擔視角 |
|---|---|
| DRY | 減少重複 = 減少需要記憶的版本 |
| SOLID | 每個原則都在降低特定類型的認知負擔 |
| Clean Code | 可讀性 = 低認知負擔 |
| 自然語言程式設計 | 讓程式碼像閱讀文章一樣自然 |
使用方式
評估任務複雜度
# 在開始任務前，快速評估
# 回答以下問題：
1. 這個任務需要修改幾個檔案？
2. 需要追蹤幾個變數狀態？
3. 跨越幾個架構層級？
4. 依賴幾個其他模組？
# 如果任一項超過閾值，考慮拆分任務
程式碼品質評估
# 在 Code Review 時，檢查：
1. 函式長度（應 5-15 行）
2. 參數數量（應 <= 3）
3. 巢狀深度（應 <= 3）
4. 變數數量（應 < 5）
相關文件
- 認知負擔量化標準 - 詳細閾值參考
- 認知負擔設計方法論 - 完整理論基礎
- 自然語言程式設計方法論 - 命名最佳實踐
- 代理人職責矩陣 - 升級判斷標準
- 任務拆分指南 - 拆分方法
Last Updated: 2026-01-28 Version: 1.1.0