程式碼整潔之道
🧭 心態：童子軍規則
🏷 命名
⚙️ 函式
💬 註解
⚠️ 錯誤處理
🧪 類別、邊界與測試
離開時讓程式碼 比你來時更乾淨一點
你寫程式的時間， 遠少於你讀程式的時間
🎯 什麼情境該想到我
當你在替變數/函式/類別取名字，或看到一堆 d、tmp、data 看不懂時。
⚙️ 怎麼用
- 名字要能回答：它是什麼、為何存在、怎麼用。看到名字就不用再看註解。
- 用可讀、可搜尋的名字：
elapsedTimeInDays勝過d；避免單字母（迴圈計數例外）。 - 別用誤導性名字、別加型別雜訊（匈牙利命名法過時）。
- 類別用名詞、函式用動詞；同一概念用同一個字（別 fetch/get/retrieve 混用）。
🧪 我實際套用的紀錄
- 2026-07-14：（待填）
⚠️ 注意
- 想不到好名字，往往代表那段職責不清 → 該先釐清設計，命名是設計的鏡子。
🔗 相關工具
- 工具-函式短小且單一職責 —— 取不出好名字通常是職責不清；把函式切到只做一件事，名字往往自己浮出來
- 工具-縮小變數作用域 —— 降低閱讀心智負擔的另一半：作用域夠小時，短名字不但無妨還更好讀
🎯 什麼情境該想到我
當一個函式很長、要捲很久、或你發現它「先…再…然後…」做很多事時。
⚙️ 怎麼用
- 只做一件事：函式內的敘述應在同一抽象層次；「還能再被有意義地拆出一個函式」就代表它不只做一件事。
- 越短越好：理想幾行；巢狀縮排別太深。
- 參數越少越好：0–2 個最佳，3 個以上考慮包成物件；避免旗標參數（傳 boolean 通常代表函式做了兩件事）。
- 無副作用：函式名說做什麼，就別偷偷做別的。
🧪 我實際套用的紀錄
- 2026-07-14：（待填）
⚠️ 注意
- 拆函式讓抽象層次一致，不是為短而短；配合 工具-提煉函式 手法安全地拆。
🔗 相關工具
- 工具-有意義的命名 —— 配套：函式拆小之後，名字是否說得清它做什麼就是驗收標準
- 工具-提煉函式 —— 執行手法，這張講「該多小」，它講「怎麼拆出去」
- 工具-一次只做一件事 —— 同一原則的段落層說法，可用來判斷函式內部還該不該再切
🎯 什麼情境該想到我
當你正想加一段註解來「解釋」一段程式碼時，先停一下。
⚙️ 怎麼用
- 先試著用程式碼表達：把那段抽成一個命名清楚的函式，往往就不需要註解了。
- 註解是表達的失敗：能用命名/結構說清楚就別靠註解。
- 好註解：法律聲明、意圖說明、警告、TODO、對公開 API 的說明。
- 壞註解：多餘（複述程式碼）、誤導、被註解掉的死程式碼（直接刪，交給版本控制）、跟程式不同步的過時註解。
🧪 我實際套用的紀錄
- 2026-07-14：（待填）
⚠️ 注意
- 註解不會隨程式碼自動更新 → 過時註解比沒有更糟。
🔗 相關工具
- 工具-有意義的命名 —— 第一替代方案，多數註解可以被一個好名字取代
- 工具-函式短小且單一職責 —— 第二替代方案，需要註解分段時通常代表該拆函式了
🎯 什麼情境該想到我
當你的程式碼被一堆「檢查回傳值/錯誤碼」的 if 淹沒，或常被 null 炸到時。
⚙️ 怎麼用
- 用例外（Exception）而非回傳錯誤碼：讓正常流程乾淨，錯誤處理分離。
- 別回傳 null，也別傳 null 當參數：改回傳空集合、Optional，或丟例外。
- 例外訊息要有情境：說清楚哪裡、為什麼失敗。
- 把 try/catch 的主體抽成獨立函式，讓錯誤處理成為「一件事」。
🧪 我實際套用的紀錄
- 2026-07-14：（待填）
⚠️ 注意
- 別用例外控制正常流程；例外是給「意外」用的。
🔗 相關工具
- 工具-函式短小且單一職責 —— 直接效果，錯誤處理抽走之後主流程才看得出在做什麼
- 工具-防禦式編程 —— 界線劃分，哪些該丟例外、哪些該在邊界就擋掉，用它判斷
類別要小：單一職責、高內聚
整潔的邊界：包裝第三方程式碼
單元測試 F.I.R.S.T Fast / Independent / Repeatable / Self-validating / Timely