tai-ch0802/code-quality

程式碼品質 — 標準與審查

關鍵技能 — 保持簡潔、直接、以解決方案為導向。

---

核心原則

| 原則 | 規則 | |------|------| | SRP | 單一職責 — 每個函式/類別只做一件事 | | DRY | 不要重複自己 — 提取重複，重用 | | KISS | 保持簡單 — 最簡單且能運作的方案 | | YAGNI | 你不會需要它 — 不建置未使用的功能 | | 童子軍 | 讓程式碼比你發現時更乾淨 |

---

命名規則

| 元素 | 慣例 | |------|------| | 變數 | 揭示意圖：userCount 而非 n | | 函式 | 動詞 + 名詞：getUserById() 而非 user() | | 布林值 | 問句形式：isActive、hasPermission、canEdit | | 常數 | SCREAMING_SNAKE：MAX_RETRY_COUNT |

規則： 如果你需要註解來解釋名稱，那就重新命名它。

---

函式規則

| 規則 | 說明 | |------|------| | 小 | 最多 20 行，理想 5-10 行 | | 一件事 | 做一件事，做好它 | | 一個層級 | 每個函式一個抽象層級 | | 少參數 | 最多 3 個參數，偏好 0-2 個 | | 無副作用 | 不意外地修改輸入 |

---

程式碼結構

| 模式 | 應用 | |------|------| | 守衛子句 | 邊界案例提前回傳 | | 扁平 > 巢狀 | 避免深層巢狀（最多 2 層） | | 組合 | 小函式組合在一起 | | 共置 | 保持相關程式碼靠近 |

---

程式碼審查清單

正確性

• [ ] 程式碼做了該做的事
• [ ] 邊界案例已處理
• [ ] 錯誤處理到位
• [ ] 沒有明顯的 bug

安全性

• [ ] 輸入已驗證和清理
• [ ] 沒有 SQL/NoSQL 注入漏洞
• [ ] 沒有 XSS 或 CSRF 漏洞
• [ ] 沒有寫死的秘密或敏感憑證
• [ ] AI 特定： 防護 Prompt 注入（如適用）
• [ ] AI 特定： 輸出在用於關鍵接收點前已清理

效能

• [ ] 沒有 N+1 查詢
• [ ] 沒有不必要的迴圈
• [ ] 適當的快取
• [ ] 已考慮打包大小影響

測試

• [ ] 新程式碼有單元測試
• [ ] 邊界案例已測試
• [ ] 測試可讀且可維護

文件

• [ ] 複雜邏輯有註解
• [ ] 公開 API 已記錄
• [ ] README 已更新（如需要）

---

AI 與 LLM 審查模式（2025）

邏輯與幻覺

• [ ] 思維鏈： 邏輯是否遵循可驗證的路徑？
• [ ] 邊界案例： AI 是否考慮了空狀態、逾時和部分失敗？
• [ ] 外部狀態： 程式碼是否對檔案系統或網路做了安全的假設？

Prompt 工程審查

// ❌ 程式碼中模糊的 prompt
const response = await ai.generate(userInput);

// ✅ 結構化且安全的 prompt
const response = await ai.generate({
  system: "You are a specialized parser...",
  input: sanitize(userInput),
  schema: ResponseSchema
});

---

反模式

| ❌ 模式 | ✅ 修復 | |---------|---------| | 每行都註解 | 刪除顯而易見的註解 | | 為一行程式碼建立 helper | 內聯程式碼 | | 為 2 個物件建立 Factory | 直接實例化 | | 只有 1 個函式的 utils.ts | 把程式碼放在使用處 | | "首先我們匯入..." | 直接寫程式碼 | | 深層巢狀 | 守衛子句 | | 魔術數字 | 具名常數 | | 上帝函式 | 按職責拆分 | | any 型別 | 正確的型別 | | 過長函式（100+ 行） | 小而專注的函式 |

---

審查評論指南

// 阻擋性問題使用 🔴
🔴 BLOCKING: 此處有 SQL 注入漏洞

// 重要建議使用 🟡
🟡 SUGGESTION: 考慮使用 useMemo 提升效能

// 小建議使用 🟢
🟢 NIT: 偏好 const 而非 let 用於不可變變數

// 問題使用 ❓
❓ QUESTION: 如果 user 為 null 這裡會怎樣？

---

AI 編碼風格

| 情境 | 行動 | |------|------| | 使用者要求功能 | 直接撰寫 | | 使用者回報 bug | 修復它，不要解釋 | | 沒有明確需求 | 詢問，不要假設 |

---

🔴 編輯任何檔案前（先思考！）

| 問題 | 原因 | |------|------| | 什麼匯入了這個檔案？ | 它們可能會壞掉 | | 這個檔案匯入了什麼？ | 介面變更 | | 什麼測試覆蓋了這裡？ | 測試可能會失敗 | | 這是共用元件嗎？ | 多處受影響 |

🔴 規則： 在同一個任務中編輯該檔案 + 所有相依的檔案。 🔴 絕不留下壞掉的匯入或遺漏的更新。

---

🔴 完成前自我檢查（強制）

| 檢查 | 問題 | |------|------| | ✅ 目標達成？ | 我做了使用者要求的事嗎？ | | ✅ 檔案已編輯？ | 我修改了所有必要的檔案嗎？ | | ✅ 程式碼能用？ | 我測試/驗證了變更嗎？ | | ✅ 沒有錯誤？ | Lint 和 TypeScript 通過了嗎？ | | ✅ 沒有遺漏？ | 有邊界案例被遺漏嗎？ |

🔴 規則： 如果任何檢查失敗，在完成前修復它。

---

總結

| 做 | 不做 | |----|------| | 直接寫程式碼 | 寫教學 | | 讓程式碼自我文件化 | 加上顯而易見的註解 | | 立即修復 bug | 先解釋修復方法 | | 內聯小東西 | 建立不必要的檔案 | | 清楚地命名 | 使用縮寫 | | 保持函式小 | 撰寫 100+ 行的函式 |

記住：使用者要的是能用的程式碼，不是程式設計課。