4.1 程式碼品質與可讀性#

程式碼是寫給人看的#

有個流傳已久的說法：「程式碼是寫給人看的，只是順便被機器執行。」

乍聽之下反直覺——程式不是要給電腦跑的嗎？但這個說法點出了一個重要事實：一段程式碼一生會被閱讀的次數，遠多於被撰寫的次數。 你現在寫的程式碼，將來會被同事、被未來的你、被維護系統的人讀成千上百次。而讀程式碼，是理解系統、修改系統、除錯系統的基礎。

面對「多一個人讀 +100 成本」的邏輯：可讀性（Readability）不是「加分項」，而是「必要品質」。 一段無法讀懂的程式碼，幾乎等於一段無法維護的程式碼。

什麼是可讀性#

可讀性沒有讀不出精確定義，但可以從幾個維度感受它：

一段「好讀」的程式碼
- 你一眼能看懂它在做什麼
- 函式和變數名能「自解釋」
- 不需要註解也能大致理解邏輯
- 段落清楚、層次分明

一段「難讀」的程式碼
- 命名模糊（a、b、x、temp）
- 一堆魔法數字（if (x > 86400)）
- 函式又長又亂、副作用一堆
- 全靠註解補救（「這裡很複雜，別改」）

提升可讀性的具體做法#

1. 有意義的命名（最重要）#

命名是最直接影響可讀性的因素。原則：

名稱要表達「意圖」而非「怎麼做」：getUserTotalSpent() 比 calc(x) 好
遵循一致的命名慣例：camelCase（變數/函式）、PascalCase（類別）、SCREAMING_CASE（常數）等
避免用錯的縮寫：custCnt 不如 customerCount 清楚
布林值用「是/否」命名：isActive、hasDiscount 比 status 清楚

命名是「父愛工程師」（Uncle Bob）最強調的事：好的命名，讓程式碼像散文一樣可讀。

2. 一次只做一件事#

一個函式/方法應該只做一件事，而且名稱能說明白那件事。這呼應 3.4 節的「單一職責原則」。如果一個函式超過幾十行、或做的事超過一件，就該拆。

例如，一個函式同時「驗證輸入 + 算折扣 + 存資料庫 + 發通知」——應該拆成多個專責函式，再依序列用。

3. 消除魔法數字與魔法字串#

直接把數字或字串「硬編碼」在邏輯中，讀者無法理解它的意義：

# 難以理解
if user.total_spent > 1000:
    discount = 0.9

# 自解釋
VIP_THRESHOLD = 1000
VIP_DISCOUNT_RATE = 0.9
if user.total_spent > VIP_THRESHOLD:
    discount = VIP_DISCOUNT_RATE

4. 控制複雜度：保持「腦子能裝得下」#

人的短期記憶只能同時追蹤少數幾個概念。過度巢狀（nested）、過長的行、過多的變數，都會讓讀者「腦子裝不下」。實務技巧：

減少巢狀深度（提早 return、把條件抽出）
每行不要太長
一個區塊內的變數數量控制在一定範圍

5. 註解：說明「為什麼」，而非「做什麼」#

一個常見誤解是「註解越多越好」。實際上：

好的程式碼自己會說話——不需要註解重複「做什麼」
註解最適合說明「為什麼」：為什麼這樣設計、這個魔法數字從哪來、這個邊界條件的背景

# 錯誤：重複說做什麼
# 把 total 乘上 0.9
total *= 0.9

# 正確：說明為什麼
# 滿 1000 元的 VIP 享 9 折（業務需求 #123）
total *= VIP_DISCOUNT_RATE

過多的「敘述性註解」代表程式碼本身不夠清楚——應該改善程式碼，而不是靠註解掩蓋。

程式碼品質的其他面向#

可讀性之外，程式碼品質還包含幾個重要面向，本節先點名，後續章節展開：

正確性（Correctness）：邏輯是否正確（第 5 章測試）
可維護性（Maintainability）：修改是否容易（3.4 節設計原則）
可擴展性（Extensibility）：能否新增功能（3.4 節 OCP）
效能（Performance）：執行效率（實作層）
安全性（Security）：是否容易受攻擊（第 13 章）

靜態分析：用工具幫你把關品質#

除了靠人讀，現代開發仰賴靜態分析工具自動檢查程式碼品質與潛在錯誤：

語言/工具	用途
ESLint（JS/TS）	檢查程式碼風格與常見錯誤
Ruff/Flake8（Python）	Python 風格與錯誤檢查
Biome	新一代的快速 lint/format
型別檢查器（TypeScript、mypy）	靜態型別檢查，提前抓型別錯誤

這些工具能在「寫完就被執行」前攔截大量低階錯誤，是品質的第一道防線。在 AI 時代（第 4.4 節）尤其重要——因為 AI 生成大量程式碼，需要自動化工具來高速審查。

本章小結#

程式碼是寫給人看的，可讀性是必要品質
提升可讀性：有意義的命名、一次只做一件事、消除魔法數字、控制複雜度、註解說明「為什麼」
程式碼品質 = 正確性 + 可維護性 + 可擴展性 + 效能 + 安全性
用靜態分析工具自動化把關品質

想一想#

找一段自己寫過的程式碼，用本節 5 項做法逐一檢查並改善，重點改善命名。
為什麼「好的命名」（）比「加註解」更能提升可讀性？
你覺得「註解『做什麼』」該不該刪掉？為什麼註解重點在「為什麼」？