SKILL.md
readonlyread-only
name
clean-code
description
此技能體現了 Robert C. Martin（Uncle Bob）所著《Clean Code》的原則。用它將「能運作的程式碼」轉變為「整潔的程式碼」。
Clean Code 技能
此技能體現了 Robert C. Martin（Uncle Bob）所著《Clean Code》的原則。用它將「能運作的程式碼」轉變為「整潔的程式碼」。
🧠 核心哲學
「程式碼若能讓非原始作者的其他開發者閱讀並增強，就是整潔的。」— Grady Booch
使用時機
在以下情況使用此技能：
- 撰寫新程式碼：確保從一開始就有高品質。
- 審查 Pull Request：提供有建設性、基於原則的回饋。
- 重構舊程式碼：識別並消除程式碼壞味道。
- 提升團隊標準：對齊業界標準的最佳實務。
1. 有意義的名稱
- 使用表達意圖的名稱：用
elapsedTimeInDays而非d。 - 避免誤導資訊：如果實際上是
Map，就不要用accountList。 - 做出有意義的區別：避免
ProductData與ProductInfo並存。 - 使用可發音/可搜尋的名稱：避免
genymdhms。 - 類別名稱：使用名詞（
Customer、WikiPage）。避免Manager、Data。 - 方法名稱：使用動詞（
postPayment、deletePage）。
2. 函式
- 小！：函式應該比你認為的還要短。
- 只做一件事：一個函式應該只做一件事，並且做好。
- 單一抽象層級：不要混雜高階商業邏輯與低階細節（如正規表達式）。
- 描述性名稱：
isPasswordValid比check好。 - 參數：0 個最理想，1-2 個還可以，3 個以上需要非常充分的理由。
- 無副作用：函式不應偷偷改變全域狀態。
3. 註解
- 不要為壞程式碼寫註解——重寫它：大多數註解是我們無法用程式碼表達自己的徵兆。
- 用程式碼解釋自己：
對比# 檢查員工是否符合全額福利資格 if employee.flags & HOURLY and employee.age > 65:if employee.isEligibleForFullBenefits(): - 好的註解：法律資訊、說明性（正規表達式意圖）、澄清（外部函式庫）、TODO。
- 壞的註解：喃喃自語、冗餘、誤導、強制、噪音、位置標記。
4. 格式
- 報紙隱喻：高階概念在上方，細節在下方。
- 垂直密度：相關的行應彼此靠近。
- 距離：變數應在其使用處附近宣告。
- 縮排：對結構可讀性至關重要。
5. 物件與資料結構
- 資料抽象化：將實作隱藏在介面之後。
- 德墨忒爾定律：一個模組不應知道它所操作物件的內部細節。避免
a.getB().getC().doSomething()。 - 資料傳輸物件（DTO）：只有公開變數而無函式的類別。
6. 錯誤處理
- 使用例外而非回傳碼：保持邏輯整潔。
- 先寫 Try-Catch-Finally：定義操作的範圍。
- 不要回傳 Null：這會強迫呼叫端每次都檢查 null。
- 不要傳入 Null：會導致
NullPointerException。
7. 單元測試
- TDD 三定律：
- 在寫好失敗的單元測試之前，不要寫任何正式程式碼。
- 不要寫超過足以失敗的單元測試。
- 不要寫超過足以通過失敗測試的正式程式碼。
- F.I.R.S.T. 原則：快速（Fast）、獨立（Independent）、可重複（Repeatable）、自我驗證（Self-Validating）、及時（Timely）。
8. 類別
- 小！：類別應只有單一職責（SRP）。
- 階層規則：我們希望程式碼讀起來像自上而下的敘述。
9. 壞味道與啟發式
- 僵化性：難以修改。
- 脆弱性：在多處容易出錯。
- 不動性：難以重複使用。
- 黏滯性：難以做正確的事。
- 不必要的複雜性/重複。
🛠️ 實作檢查清單
- [ ] 這個函式是否小於 20 行？
- [ ] 這個函式是否只做一件事？
- [ ] 所有名稱是否都可搜尋且表達意圖？
- [ ] 我是否透過讓程式碼更清晰來避免註解？
- [ ] 我是否傳入了太多參數？
- [ ] 這個變更是否有失敗的測試？
限制
- 僅在任務明確符合上述範圍時使用此技能。
- 請勿將輸出視為環境特定驗證、測試或專家審查的替代品。
- 如果缺少必要的輸入、權限、安全邊界或成功標準，請停止並要求釐清。
