認知負擔評估工具

核心理念

所有程式碼設計原則的終極目標：降低閱讀者的認知負擔

認知負擔是指閱讀者在理解程式碼時需要同時記住的資訊量。當認知負擔超過人類工作記憶的容量（約 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	可讀性 = 低認知負擔
自然語言程式設計	讓程式碼像閱讀文章一樣自然

使用方式

評估任務複雜度

bash

# 在開始任務前，快速評估
# 回答以下問題：

1. 這個任務需要修改幾個檔案？
2. 需要追蹤幾個變數狀態？
3. 跨越幾個架構層級？
4. 依賴幾個其他模組？

# 如果任一項超過閾值，考慮拆分任務

程式碼品質評估