代碼可讀性：專業開發者的核心素養
代碼給機器執行，更給人閱讀。可讀性高的代碼能降低維護成本、減少 Bug、促進團隊協作。以下 15 個最佳實踐，涵蓋命名、結構、註解、格式化等維度，助你寫出「自文檔化」的優雅代碼。
15 大核心原則
- 有意圖的命名：變數、函數、類別名稱應揭示意圖，如
getUserById() 優於 getData()。
- 避免誤導性資訊：勿用
accountList 存放非 List 結構；勿用 hp 縮寫模糊概念。
- 有區分度的命名：
ProductInfo vs ProductData 應有明確語義邊界。
- 可發音、可搜尋：避免單字母變數（迴圈索引除外），便於代碼審查與全域搜尋。
- 類別名用名詞，方法名用動詞：
User, save(), delete()。
- 每個函數只做一件事：單一職責原則，函數應短小、專注、無副作用。
- 函數參數越少越好：零參數最佳，超過三個考慮封裝為物件。
- 避免旗標參數：
render(true) 拆分為 renderForWeb(), renderForMobile()。
- 善用說明性變數：將複雜條件提取為具名變數，如
isEligible = age > 18 && hasLicense。
- 註解補充「為什麼」，而非「做什麼」：代碼本身應說明做什麼，註解解釋商業邏輯、演算法選擇、歷史經緯。
- 格式化統一：團隊制定風格指南（縮排、大括號位置、空行規則），配合工具自動格式化。
- 相關代碼靠近放置：變數宣告靠近首次使用處；呼叫關係緊密的函數垂直靠近。
- 錯誤處理與主流程分離：使用異常或 Result 物件，避免巢狀
if-else 淹沒核心邏輯。
- 邊界條件顯式處理：空集合、null、零值等邊界情況寫單元測試並明確處理。
- 持續重構：每次提交前問自己：這段代碼還能更清晰嗎？
工具輔助
- 靜態分析：PHPStan, Psalm, ESLint, SonarQube
- 格式化：PHP-CS-Fixer, Prettier, clang-format
- 代碼審查流程：Pull Request 必須經過至少一位同事審查
結語
可讀性不是天賦，是習慣。從今天開始，對每一行代碼負責，你的未來自己（與同事）會感謝你。
