《Clean Code》Podcast 準備稿：函式・註解
書名： 無瑕的程式碼 Clean Code（A Handbook of Agile Software Craftsmanship） 作者： Robert C. Martin（Uncle Bob） 系列： Reading Uncle Bob（恩普拉氏） 公開標題建議： Reading Uncle Bob｜Clean Code．函式與註解：短小、只做一件事，以及註解的雙面刃 (2/7) 涵蓋範圍： 第3章 函式 ＋ 第4章 註解
背景速覽
這集是《Clean Code》最有名、也最具爭議的一章（函式）配上最容易戳中工程師日常的一章（註解）。函式講「短小、只做一件事、單一抽象層次」；註解講「註解往往是程式碼表達失敗的補償」。兩章都很實用，但函式章正是後世對 Uncle Bob 火力最集中的地方——這集很適合一邊吸收、一邊辯證。
一句話重點
函式要短小、只做一件事、維持單一抽象層次；而最好的註解是「不需要註解」——能用更好的命名和重構讓程式碼自己說話，就別寫註解，因為註解不會跟著 code 更新，遲早變成謊言。
值得討論的重點
1. 函式三原則：短小、只做一件事、單一抽象層次
- 短小：「函式的首要規則是短小，其次是更短小。」
if/else/while區塊最好只有一行（通常是一個函式呼叫）。能拆成「初始化區／處理區／結束區」就代表做太多了。 - 只做一件事（SRP）：把它做好、且只做這件事。
- 單一抽象層次：別在同一個函式裡混「高階業務邏輯」和「低階字串處理」。
- 參數越少越好：0 > 1 > 2 >> 3；超過三個通常該包成物件。避免「輸出型參數」、避免旗標參數（傳 bool 通常代表做了兩件事）。
- 命令與查詢分離（CQS）：一個函式要嘛「做事改狀態」，要嘛「回答問題」，別兩者都做。
2. 用多型／表格取代 switch（這條留意爭議）
Uncle Bob 主張 switch 天生做「N 件事」、違反 SRP/OCP，建議用多型或 dictionary/map 取代。這在 OOP 設計裡常成立，但也是全書被批評最猛的一點（見注意事項）。
3. 註解是雙面刃：先想能不能不寫
- 核心立場：「別給爛 code 寫註解——重寫它。」最好的文件是 code 本身。
- 少數好註解：法律聲明、資訊型（解釋正則）、解釋意圖（為什麼這樣做）、告誡後果（thread-unsafe）、TODO、放大重要性。
- 壞註解（多數）：冗餘（
i++; // increment i）、誤導/過時、日誌型與簽名（交給 Git）、被註解掉的程式碼（最該直接刪，別怕，Git 記得）。
注意事項
⚠️ 函式章是《Clean Code》爭議的震央，務必平衡呈現。 Uncle Bob 自己示範的「函式拆到 2–4 行」常被批評為矯枉過正——把一個連貫邏輯炸成十幾個只被呼叫一次的小函式，反而增加跳轉、傷害可讀性，這正是 John Ousterhout《A Philosophy of Software Design》反對的「淺模組過多」。建議框成：「短小是好方向，但目標是『一眼看懂』而不是『行數最少』；過度拆分也是一種壞味道。」
⚠️ 「用多型取代 switch」有效能代價。 遊戲／高效能領域名人 Casey Muratori 的〈Clean Code, Horrible Performance〉就拿這條開刀——多型的虛函式呼叫比 switch 慢很多。要提醒聽眾：這是「可讀性 vs 效能」的取捨，看場景；不是所有 switch 都該被消滅。
⚠️ 註解章的「註解＝失敗」說法偏絕對。實務上解釋「為什麼」的註解極有價值（為何繞過某個 bug、為何選這個演算法）——Uncle Bob 其實也把「解釋意圖」列為好註解，講的時候別讓聽眾誤會成「所有註解都是壞的」。
專家補充
💡 一個好用的判準幫聽眾調和「短小 vs 過度拆分」：抽取函式的理由應該是「給一段邏輯一個好名字、消除重複、或分離抽象層次」，而不是「為了讓行數變少」。 如果抽出來的函式只被呼叫一次、又取不出好名字、還讓你得跳來跳去讀——那就不該抽。
💡 CQS（命令查詢分離）可以連到更大的概念：它是 CQRS（書庫裡也有專書）的思想前身，也是函數式程式設計「純函式 vs 副作用」的同源直覺。Uncle Bob 的「避免副作用」其實在向 FP 靠攏——這也呼應系列最後一本《Functional Design》。
💡 「被註解掉的程式碼」這條值得用力推：它是團隊 codebase 腐敗的典型訊號——沒人敢刪，因為不知道是不是還有用。一句話送聽眾：「Git 就是你的時光機，註解掉的 code 是你不信任 Git 的證據。」
討論問題
🎙️ 開場鉤子：「『函式要短小』聽起來像廢話——但 Uncle Bob 說的『短』，短到可能會讓你嚇一跳。問題是：短到極致，真的比較好讀嗎？」
🎙️ 自問自答（辯證）：「把一個 50 行函式拆成 15 個 3 行小函式，到底是變乾淨了，還是只是把複雜度藏到別處？」——帶出 Ousterhout 的反方觀點，讓這集有思辨張力。
🎙️ 帶走的一題：「打開你的專案，搜尋有沒有『被註解掉的程式碼』。找到就刪掉——相信 Git。」
更大範圍關聯
- 對照組：John Ousterhout《A Philosophy of Software Design》——「深模組」主張與本章「小函式」直接對話，是這季最值得做的一集對照（甚至可做成【主題】跨書集）。
- 效能視角：Casey Muratori〈Clean Code, Horrible Performance〉、Data-Oriented Design 一脈，是「整潔 vs 效能」辯論的另一極。
- 同源概念：CQS → CQRS（書庫有專書）→ 函數式的純函式；副作用最小化接系列終卷《Functional Design》。
- DRY：函式章的「不重複自己」接《Pragmatic Programmer》的 DRY 原則。
錄製建議
- 建議時長：約 20 分鐘。函式約 11 分（含爭議辯證）、註解約 8 分。
- 討論策略：函式章建議「先正講 Uncle Bob 的原則（短小、一件事、少參數、CQS），再誠實補上爭議（過度拆分、switch 效能）」——這種「先吸收後辯證」的結構，正是 Reading Uncle Bob 系列的招牌調性，比單純複述更有看點。註解章用「被註解掉的 code」這個人人有共鳴的痛點收尾。
- 單人主講時，函式的「好/壞對照」與 switch→map 的範例都很適合口頭演示（描述 before/after），聽眾跟得上。