程式碼之美：從命名規範、註釋藝術到排版風格的工程師修養

程式碼不僅是給電腦執行的指令，更是給人閱讀、維護、傳承的文獻。本文不談語法技巧，專注於編碼風格——命名、註釋、排版、介面設計——這些決定專案長期存活品質的軟性實力。

一、註釋：為「不顯而易見」的邏輯留下地圖

• 不要註解顯而易見的事：i := i + 1; // i 加 1 只會增加噪音
• 註解「為什麼」而非「做什麼」：演算法選擇理由、業務規則由來、避開的坑
• 函式/全域變數/常數/類別定義 必須有單行說明
• 複雜演算法 附上參考文獻連結或推導摘要
• 好的程式碼本身即文件：命名清晰、結構單一，註釋自然稀少；爛程式碼堆砌註釋也救不回可讀性

二、命名：一致性勝過創意

專案內統一慣例，若無慣例，請先建立一份 CodingStyle.md。

三、排版：結構可視化

• 縮排統一：2 或 4 空格，禁用 Tab 混用
• 括號風格統一：begin ... end 或 { ... } 選一堅持
• 巢狀超過 3 層 立即重構提取函式
• 複雜表達式加括號 消除優先序歧義：if (a and b) or (c and d) then
• 長表達式拆解：引入中間變數 HasPermission := (User.Role = 'Admin') and (Resource.Owner = User.Id);
• 副作用隔離：函式盡量無副作用；有副作用者命名明確（SaveAndNotify）

四、介面設計風格：對呼叫者負責

• 隱藏實作細節：公開介面只暴露「做什麼」，不洩露「怎麼做」
• 資源釋放與配對在同一層次：Create/Free、Open/Close、Lock/Unlock 成對出現於同一函式層級
• 底層檢查錯誤，高層處理：底層回傳錯誤碼/拋出例外，高層決策重試、記錄、轉向
• 例外僅用於例外狀況：流程控制勿用 try...except 替代 if
• 一致的錯誤處理慣用語：全專案統一 Result := False; Exit; 或 raise 模式

五、風格即習慣：從今天開始

風格不是文檔，是肌肉記憶。寫第一行碼時就在意縮排、命名、括號，久而久之潛意識接管細節，即便在趕工期壓力下，產出的碼依然整潔。草率的碼不僅難讀，更藏著崩潰的種子；好風格是降低維護成本、提升團隊信任的最高性價比投資。

「程式寫給人看，順便能在電腦上跑。」—— Harold Abelson, SICP