# Code Quality

> 務實的編碼標準與程式碼審查指南。涵蓋命名、函式、反模式、審查清單及 AI 特定的審查模式。取代 clean-code + code-review-checklist。

- Skill: `tai-ch0802/code-quality-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tai-ch0802/code-quality-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tai-ch0802/code-quality-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Tai-ch0802 (https://skillmd.com/u/tai-ch0802)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/tai-ch0802/code-quality-2

---


# 程式碼品質 — 標準與審查

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

---

## 核心原則

| 原則 | 規則 |
|------|------|
| **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 工程審查
```markdown
// ❌ 程式碼中模糊的 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+ 行的函式 |

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