🎯 什麼情境該想到我
當你正想加一段註解來「解釋」一段程式碼時，先停一下。
⚙️ 怎麼用
- 先試著用程式碼表達：把那段抽成一個命名清楚的函式，往往就不需要註解了。
- 註解是表達的失敗：能用命名/結構說清楚就別靠註解。
- 好註解：法律聲明、意圖說明、警告、TODO、對公開 API 的說明。
- 壞註解：多餘（複述程式碼）、誤導、被註解掉的死程式碼（直接刪，交給版本控制）、跟程式不同步的過時註解。
🧪 我實際套用的紀錄
- 2026-07-14：（待填）
⚠️ 注意
- 註解不會隨程式碼自動更新 → 過時註解比沒有更糟。
🔗 相關工具
- 工具-有意義的命名 —— 第一替代方案，多數註解可以被一個好名字取代
- 工具-函式短小且單一職責 —— 第二替代方案，需要註解分段時通常代表該拆函式了