Quartz 5

程式碼整潔之道 Clean Code

Properties1
tagssoftware, clean-code, craftsmanship, readability

2 min read

📌 30 秒摘要（Layer 3）

程式碼被讀的次數遠多於被寫的次數，所以可讀性就是生產力。整潔的程式碼靠一堆小紀律堆出來：取有意義的名字、函式短小只做一件事、少而精的註解、清楚的錯誤處理。核心心態是童子軍規則——每次離開時讓程式碼比你來時更乾淨一點。

🗺 心智圖（Canvas）

程式碼整潔之道

程式碼整潔之道

🧭 心態：童子軍規則

🏷 命名

⚙️ 函式

💬 註解

⚠️ 錯誤處理

🧪 類別、邊界與測試

離開時讓程式碼 比你來時更乾淨一點

你寫程式的時間， 遠少於你讀程式的時間

工具-有意義的命名

🎯 什麼情境該想到我

當你在替變數/函式/類別取名字，或看到一堆 d、tmp、data 看不懂時。

⚙️ 怎麼用

  1. 名字要能回答：它是什麼、為何存在、怎麼用。看到名字就不用再看註解。
  2. 用可讀、可搜尋的名字：elapsedTimeInDays 勝過 d；避免單字母（迴圈計數例外）。
  3. 別用誤導性名字、別加型別雜訊（匈牙利命名法過時）。
  4. 類別用名詞、函式用動詞；同一概念用同一個字（別 fetch/get/retrieve 混用）。

🧪 我實際套用的紀錄

  • 2026-07-14：（待填）

⚠️ 注意

  • 想不到好名字，往往代表那段職責不清 → 該先釐清設計，命名是設計的鏡子。

🔗 相關工具

工具-函式短小且單一職責

🎯 什麼情境該想到我

當一個函式很長、要捲很久、或你發現它「先…再…然後…」做很多事時。

⚙️ 怎麼用

  1. 只做一件事：函式內的敘述應在同一抽象層次；「還能再被有意義地拆出一個函式」就代表它不只做一件事。
  2. 越短越好：理想幾行；巢狀縮排別太深。
  3. 參數越少越好：0–2 個最佳，3 個以上考慮包成物件；避免旗標參數（傳 boolean 通常代表函式做了兩件事）。
  4. 無副作用：函式名說做什麼，就別偷偷做別的。

🧪 我實際套用的紀錄

  • 2026-07-14：（待填）

⚠️ 注意

  • 拆函式讓抽象層次一致，不是為短而短；配合 工具-提煉函式 手法安全地拆。

🔗 相關工具

工具-註解是必要之惡

🎯 什麼情境該想到我

當你正想加一段註解來「解釋」一段程式碼時，先停一下。

⚙️ 怎麼用

  1. 先試著用程式碼表達：把那段抽成一個命名清楚的函式，往往就不需要註解了。
  2. 註解是表達的失敗：能用命名/結構說清楚就別靠註解。
  3. 好註解：法律聲明、意圖說明、警告、TODO、對公開 API 的說明。
  4. 壞註解：多餘（複述程式碼）、誤導、被註解掉的死程式碼（直接刪，交給版本控制）、跟程式不同步的過時註解。

🧪 我實際套用的紀錄

  • 2026-07-14：（待填）

⚠️ 注意

  • 註解不會隨程式碼自動更新 → 過時註解比沒有更糟。

🔗 相關工具

工具-用例外處理錯誤

🎯 什麼情境該想到我

當你的程式碼被一堆「檢查回傳值/錯誤碼」的 if 淹沒，或常被 null 炸到時。

⚙️ 怎麼用

  1. 用例外（Exception）而非回傳錯誤碼：讓正常流程乾淨，錯誤處理分離。
  2. 別回傳 null，也別傳 null 當參數：改回傳空集合、Optional，或丟例外。
  3. 例外訊息要有情境：說清楚哪裡、為什麼失敗。
  4. 把 try/catch 的主體抽成獨立函式，讓錯誤處理成為「一件事」。

🧪 我實際套用的紀錄

  • 2026-07-14：（待填）

⚠️ 注意

  • 別用例外控制正常流程；例外是給「意外」用的。

🔗 相關工具

類別要小：單一職責、高內聚

整潔的邊界：包裝第三方程式碼

單元測試 F.I.R.S.T Fast / Independent / Repeatable / Self-validating / Timely

Link to original

🧰 這本書給我的工具

✨ 關鍵重點（Layer 1–2）

  • 童子軍規則：離開時讓程式碼比來時更乾淨。
  • 命名：名字要能回答「它是什麼、為何存在、怎麼用」。
  • 函式：越短越好、只做一件事、參數越少越好、無副作用。
  • 註解：註解常是「表達失敗」的補償；能用程式碼表達就別寫註解。
  • 錯誤處理：用例外而非回傳碼；別回傳 null、也別傳 null。
  • 整潔的邊界、單元測試（F.I.R.S.T）、類別要小。

💬 金句原文（Layer 0）

  • 「你寫程式的時間，遠少於你讀程式的時間。」
  • 「函式應該只做一件事，把它做好，而且只做這件事。」

🔗 相關

  • 重構 —— 配套型錄，本書講什麼叫乾淨，那本給 54 個把它變乾淨的具體手法

Graph View

Backlinks