Tai-ch0802 程式碼品質 — 標準與審查
關鍵技能 — 保持簡潔、直接、以解決方案為導向。
核心原則
| 原則 | 規則 |
|---|---|
| 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+ 行的函式 |
記住：使用者要的是能用的程式碼，不是程式設計課。