第1章 什麼是 Clean Code

▌1-1 乾淨程式碼的定義與價值

1-1-1 什麼是乾淨程式碼

1-1-2 乾淨程式碼的核心特徵

1-1-3 為什麼需要乾淨程式碼

1-1-4 乾淨程式碼與技術債

▌1-2 好程式與壞程式的對比

1-2-1 壞程式碼的典型特徵

1-2-2 好程式碼的特徵

1-2-3 案例對比 - 從壞程式到好程式

1-2-4 從對比中學到的啟示



第2章 Python 語言特色與常見誤用

▌2-1 Pythonic vs Non-Pythonic

2-1-1 什麼是 Pythonic

2-1-2 Non-Pythonic 的典型寫法

2-1-3 常見範例對比

2-1-4 程式邏輯語義化 - any( )/all( )

2-1-5 為什麼要寫 Pythonic 程式碼

▌2-2 常見 Python 惡習

2-2-1 什麼是「程式惡習」

2-2-2 認識「耦合度」

2-2-3 認識「內聚」

2-2-4 常見 Python 惡習類型與改進建議

2-2-5 避免惡習的原則

▌2-3 認識PEP 與PEP 8

2-3-1 PEP 8 名稱緣由

2-3-2 PEP 8 的核心原則

2-3-3 其他與Clean Code 相關的PEP 條目



第3章 簡潔程式碼的五大原則

▌3-1 可讀性（Readability）

3-1-1 為什麼可讀性比執行效能更重要

3-1-2 清楚命名的技巧（變數、函數、類別）

3-1-3 適度使用註解與文件字串（docstring）

3-1-4 善用 Python 語言特性提升可讀性

▌3-2 可維護性（Maintainability）

3-2-1 什麼是可維護程式碼

3-2-2 減少重複（DRY 原則）

3-2-3 模組化設計與程式結構規劃

3-2-4 自動化測試與版本控制的輔助角色

▌3-3 單一職責（Single Responsibility Principle, SRP）

3-3-1 SRP 的定義與意義

3-3-2 為什麼「包山包海」的函數是壞習慣

3-3-3 將功能拆分為小型模組的實務方法

▌3-4 低耦合（Low Coupling）

3-4-1 耦合的定義與分類（資料耦合、控制耦合、全域耦合等）

3-4-2 高耦合帶來的風險與技術債

3-4-3 如何降低耦合 - 參數傳遞、抽象化、依賴注入

3-4-4 Python 範例 - 全域變數依賴 vs. 參數傳遞設計

▌3-5 高內聚（High Cohesion）

3-5-1 內聚的定義與重要性

3-5-2 高內聚 vs. 低內聚的比較

3-5-3 如何提高內聚 - 單一責任、清楚模組邊界

3-5-4 Python 範例 - 將輸入、邏輯、輸出分離的設計



第4章 命名原則與慣例

▌4-1 命名的重要性

4-1-1 為何命名會直接影響程式的可讀性與維護性

4-1-2 好命名與壞命名的差異比較

4-1-3 「程式即文件」的觀念 - 命名如何取代多餘註解

▌4-2 變數命名實務

4-2-1 命名原則 - 語意清楚、避免縮寫、保持一致

4-2-2 常見錯誤命名 vs. 改進範例

4-2-3 特殊情境 - 常數與布林變數命名

4-2-4 Python 命名慣例 - snake_case/camelCase

▌4-3 函數命名實務

4-3-1 函數命名應以動詞或動詞片語為主

4-3-2 命名表達「做什麼」，而不是「怎麼做」

4-3-3 範例對比 data() vs. fetch_user_data()

▌4-4 類別命名實務

4-4-1 PEP 8 的PascalCase 的慣例

4-4-2 類別命名以名詞或名詞片語為主

4-4-3 如何讓類別名稱反映「它代表什麼」



第5章 註解與文件化

▌5-1 註解該寫在哪裡、不該寫什麼

5-1-1 註解的角色 - 補充「為什麼」，而非重複「做什麼」

5-1-2 該寫的註解

5-1-3 不該寫的註解

5-1-4 註解的最佳實踐

▌5-2 使用 docstring 寫出清楚的說明

5-2-1 什麼是 docstring ？與一般註解的差異

5-2-2 docstring 的用途

5-2-3 docstring 的撰寫格式 -（ 單行、多行、常見風格）

5-2-4 撰寫清楚 docstring 的最佳實踐



第6章 程式碼格式化與排版

▌6-1 再談PEP 8 規範

6-1-1 PEP 8 的角色與重要性

6-1-2 核心規範

6-1-3 PEP 8 與程式碼審查

▌6-2 常用工具 - black、isort、flake8

6-2-1 black 自動格式化工具

6-2-2 isort 自動整理匯入順序

6-2-3 flake8 程式碼檢查工具



第7章 函數設計原則

▌7-1 函數應該只做一件事

7-1-1 單一職責原則在函數層級的應用

7-1-2 壞範例 - 包山包海的函數

7-1-3 好範例 - 將函數拆分成小而清楚的單元

7-1-4 優點 - 可讀性、可測試性、可維護性

▌7-2 避免副作用

7-2-1 什麼是副作用？為什麼要避免？

7-2-2 常見的副作用類型

7-2-3 如何控制副作用

7-2-4 純函數的優勢

▌7-3 參數數量控制

7-3-1 為什麼過多參數會降低可讀性與可測試性

7-3-2 控制參數數量的實務方法

7-3-3 壞範例 vs 好範例（過多參數的重構對比）



第8章 物件導向與類別設計

▌8-1 善用 class 與 method 的封裝性

8-1-1 類別的核心價值 - 資料與行為的結合

8-1-2 為什麼要使用封裝

8-1-3 壞範例 - 所有邏輯寫在全域函數

8-1-4 好範例 - 使用類別封裝資料與操作

8-1-5 善用公開方法與私有方法的分工

▌8-2 不過度設計

8-2-1 什麼是過度設計

8-2-2 壞範例 - 單純功能卻被拆成過多類別

8-2-3 好範例 - 保持設計簡單，類別數量與責任相符

8-2-4 YAGNI 原則 - 不要為了未來而過早設計

▌8-3 不過度抽象

8-3-1 抽象化的價值與風險

8-3-2 壞範例 - 不必要的繼承或介面層

8-3-3 好範例 - 在必要時才抽象，保持彈性與可讀性。

8-3-4 KISS 原則 - 保持簡單，避免不必要的抽象



第9章 模組化與檔案結構整理

▌9-1 拆分功能模組的策略

9-1-1 何謂模組化？為何模組化能降低複雜度

9-1-2 拆分原則 - 單一職責、低耦合、高內聚

9-1-3 何時該拆模組

9-1-4 範例 - 將單一大檔案重構為多個模組

9-1-5 模組間的依賴控制 - 避免循環匯入

▌9-2 常見小型專案目錄結構範例



第10章 單元測試

▌10-1 測試的重要性

10-1-1 為什麼需要測試？

10-1-2 測試的層級與類型簡介

10-1-3 測試在乾淨程式碼中的角色

▌10-2 使用 unittest 撰寫測試

10-2-1 Python 內建測試框架 unittest

10-2-2 常見斷言方法

10-2-3 測試資料的準備與清理（setUp / tearDown）

▌10-3 使用 pytest 撰寫測試

10-3-1 pytest 的基本用法

10-3-2 pytest 參數

10-3-3 使用 fixture 管理測試資源

10-3-4 pytest 進階功能



第11章 錯誤處理與例外管理

▌11-1 try/except 的最佳實踐

11-1-1 try/except/else/finally 基本語法回顧

11-1-2 避免過度捕捉 - 不要用「大雜燴 except」

11-1-3 精準處理 - 捕捉特定例外，而不是所有錯誤

11-1-4 使用 finally 做資源清理

11-1-5 使用 else 區塊分離「正常邏輯」與「例外邏輯」

11-1-6 完整錯誤處理模式實例

▌11-2 自定義例外的使用場景

11-2-1 什麼時候需要自定義例外？

11-2-2 定義自訂例外類別

11-2-3 加入額外資訊 - 錯誤碼與使用者資訊

11-2-4 專案範例 - 訂單處理系統中的自定義例外

11-2-5 小心過度設計 - 避免建立太多沒意義的例外類別



第12章 日誌紀錄與除錯技巧

▌12-1 使用 logging 模組

12-1-1 為什麼不要只用 print() ？

12-1-2 logging 基本用法

12-1-3 設定輸出格式與檔案紀錄

12-1-4 在專案中的最佳實踐

▌12-2 除錯的最佳策略與工具

12-2-1 為什麼只靠「印變數」是不夠的？

12-2-2 除錯策略

12-2-3 Python 常見除錯工具



第13章 程式碼壞味道重構的原則與方法

▌13-1 何時需要重構 – 程式碼壞味道

13-1-1 程式碼壞味道 (Code Smells) 的徵兆

13-1-2 技術債 (Technical Debt) 的警訊

▌13-2 小步快走 - 由壞變好

13-2-1 重構的核心精神

13-2-2 實踐方法

13-2-3 過長 if – elif - else 的重構?