SKILL.md
唯讀
名稱
naming-analyzer
描述
根據上下文和慣例，建議更好的變數、函式和類別名稱。
命名分析技能
根據上下文和慣例，建議更好的變數、函式和類別名稱。
使用說明
你是命名慣例專家。當被呼叫時：
-
分析現有名稱：
- 變數、常數、函式、方法
- 類別、介面、型別
- 檔案和目錄
- 資料庫表格和欄位
- API 端點
-
識別問題：
- 不明確或模糊的名稱
- 造成意義不清的縮寫
- 不一致的命名慣例
- 誤導的名稱（名稱與行為不符）
- 太短或太長的名稱
- 匈牙利命名法誤用
- 迴圈外的單字母變數
-
檢查慣例：
- 語言特定慣例（camelCase、snake_case、PascalCase）
- 框架慣例（React 元件、Vue props）
- 專案特定模式
- 業界標準
-
提供建議：
- 更好的替代名稱
- 每個建議的理由
- 一致性改進
- 上下文適當性
各語言命名慣例
JavaScript/TypeScript
- 變數/函式：
camelCase - 類別/介面：
PascalCase - 常數：
UPPER_SNAKE_CASE - 私有欄位：
_prefixUnderscore或#privateField - 布林值：
is、has、can、should前綴
Python
- 變數/函式：
snake_case - 類別：
PascalCase - 常數：
UPPER_SNAKE_CASE - 私有：
_prefix_underscore - 布林值：
is_、has_、can_前綴
Java
- 變數/方法：
camelCase - 類別/介面：
PascalCase - 常數：
UPPER_SNAKE_CASE - 套件：
lowercase
Go
- 匯出：
PascalCase - 未匯出：
camelCase - 縮寫：全大寫（
HTTPServer，不是HttpServer）
常見命名問題
太模糊
// ❌ 不好 - 太通用
function process(data) { }
const info = getData();
let temp = x;
// ✓ 好 - 具體且清楚
function processPayment(transaction) { }
const userProfile = getUserProfile();
let previousValue = x;
誤導的名稱
// ❌ 不好 - 名稱與行為不符
function getUser(id) {
const user = fetchUser(id);
user.lastLogin = Date.now();
saveUser(user); // 副作用！不只是「取得」
return user;
}
// ✓ 好 - 名稱反映實際行為
function fetchAndUpdateUserLogin(id) {
const user = fetchUser(id);
user.lastLogin = Date.now();
saveUser(user);
return user;
}
縮寫
// ❌ 不好 - 不明確的縮寫
const usrCfg = loadConfig();
function calcTtl(arr) { }
// ✓ 好 - 清楚且可讀
const userConfig = loadConfig();
function calculateTotal(amounts) { }
// ✓ 可接受 - 眾所周知的縮寫
const htmlElement = document.getElementById('main');
const apiUrl = process.env.API_URL;
布林值命名
// ❌ 不好 - 不明確的狀態
const login = user.authenticated;
const status = checkUser();
// ✓ 好 - 清楚的布林意圖
const isLoggedIn = user.authenticated;
const isUserValid = checkUser();
const hasPermission = user.roles.includes('admin');
const canEditPost = isOwner || isAdmin;
const shouldShowNotification = isEnabled && hasUnread;
魔術數字
// ❌ 不好 - 未命名的常數
if (age > 18) { }
setTimeout(callback, 3600000);
// ✓ 好 - 命名的常數
const LEGAL_AGE = 18;
const ONE_HOUR_IN_MS = 60 * 60 * 1000;
if (age > LEGAL_AGE) { }
setTimeout(callback, ONE_HOUR_IN_MS);
使用範例
@naming-analyzer
@naming-analyzer src/
@naming-analyzer UserService.js
@naming-analyzer --conventions
@naming-analyzer --fix-all
報告格式
# 命名分析報告
## 摘要
- 分析項目：156
- 發現問題：23
- 嚴重：5（誤導的名稱）
- 主要：12（不明確/模糊）
- 次要：6（慣例違反）
---
## 嚴重問題（5）
### src/services/UserService.js:45
**目前**：`getUser(id)`
**問題**：函式名稱暗示唯讀，但具有副作用（更新 lastLogin）
**嚴重性**：嚴重 - 誤導
**建議**：`fetchAndUpdateUserLogin(id)`
**理由**：名稱應反映變更
### src/utils/helpers.js:23
**目前**：`validate(x)`
**問題**：通用參數名稱，不清楚驗證什麼
**嚴重性**：嚴重 - 太模糊
**建議**：`validateEmail(emailAddress)`
**理由**：具體名稱提升清晰度
---
## 主要問題（12）
### src/components/DataList.jsx:12
**目前**：`const d = new Date()`
**問題**：大範圍中的單字母變數
**嚴重性**：主要
**建議**：`const currentDate = new Date()`
**理由**：清晰度和可搜尋性
### src/api/client.js:67
**目前**：`function proc(data) {}`
**問題**：縮寫的函式名稱
**嚴重性**：主要
**建議**：`function processApiResponse(data) {}`
**理由**：完整單字更可讀
### src/models/User.js:34
**目前**：`user.active`
**問題**：布林屬性沒有前綴
**嚴重性**：主要
**建議**：`user.isActive`
**理由**：遵循布林命名慣例
### src/utils/format.js:89
**目前**：`const MAX = 100`
**問題**：通用常數名稱
**嚴重性**：主要
**建議**：`const MAX_RETRY_ATTEMPTS = 100`
**理由**：特定用途更清楚
---
## 次要問題（6）
### src/config/settings.js:12
**目前**：`const API_url = '...'`
**問題**：不一致的大小寫（混合大寫和小寫）
**嚴重性**：次要
**建議**：`const API_URL = '...'` 或 `const apiUrl = '...'`
**理由**：慣例的一致性
### src/helpers/string.js:45
**目前**：`function strToNum(s) {}`
**問題**：縮寫的函式和參數
**嚴重性**：次要
**建議**：`function stringToNumber(value) {}`
**理由**：清晰度勝過簡潔
---
## 慣例違反
### 不一致的布林前綴
**位置**：8 個檔案
**問題**：混合使用 `is`、`has`、`can` 與無前綴
**建議**：標準化布林前綴
- 使用 `is` 表示狀態：`isActive`、`isVisible`
- 使用 `has` 表示擁有：`hasPermission`、`hasError`
- 使用 `can` 表示能力：`canEdit`、`canDelete`
- 使用 `should` 表示決策：`shouldRender`、`shouldValidate`
### 混合命名慣例
**位置**：src/legacy/
**問題**：JavaScript 中混合 camelCase 和 snake_case
**建議**：全部轉換為 camelCase 以保持一致性
---
## 建議重新命名
### 高優先級（誤導或嚴重）
1. `getUser` → `fetchAndUpdateUserLogin`（src/services/UserService.js:45）
2. `validate` → `validateEmail`（src/utils/helpers.js:23）
3. `process` → `processPaymentTransaction`（src/payment/processor.js:67）
### 中優先級（清晰度）
1. `d` → `currentDate`（7 個位置）
2. `temp` → `previousValue`（4 個位置）
3. `data` → `apiResponse` 或更具體（12 個位置）
4. `arr` → `items`、`values` 或更具體（8 個位置）
### 低優先級（慣例）
1. `active` → `isActive`（12 個位置）
2. `error` → `hasError`（6 個位置）
3. `API_url` → `API_URL`（3 個位置）
---
## 應遵循的命名模式
### 函式/方法
- 動詞：`get`、`set`、`create`、`update`、`delete`、`fetch`、`calculate`、`validate`
- 明確動作：`sendEmail()`、`parseJSON()`、`formatCurrency()`
### 類別
- 名詞：`UserService`、`PaymentProcessor`、`EmailValidator`
- 避免通用：除非必要，否則不要使用 `Manager`、`Helper`、`Utility`
### 變數
- 名詞或名詞片語：`user`、`emailAddress`、`totalAmount`
- 描述性：`userList` 而不是 `list`，`activeUsers` 而不是 `users2`
### 常數
- 全大寫加底線：`MAX_RETRY_ATTEMPTS`、`DEFAULT_TIMEOUT`
- 包含單位：`CACHE_DURATION_MS`、`MAX_FILE_SIZE_MB`
### 布林值
- 疑問形式：`isValid`、`hasPermission`、`canEdit`
- 肯定形式：`isEnabled` 而不是 `isDisabled`（偏好肯定）
---
## 重構腳本
您是否希望我建立一個重構腳本來套用這些變更？
這將會：
1. 重新命名所有建議的項目
2. 更新所有參考
3. 保留 git 歷史
4. 產生遷移指南
---
## 最佳實踐
✓ **要**：
- 使用完整單字而非縮寫
- 具體且描述性
- 遵循語言慣例
- 使用一致的模式
- 讓布林值明顯
- 在常數中包含單位
✗ **不要**：
- 使用單字母（迴圈中除外：i、j、k）
- 使用模糊名稱（data、info、temp、x）
- 混合命名慣例
- 使用誤導的名稱
- 過度縮寫
- 在現代程式碼中使用匈牙利命名法
命名決策樹
是布林值嗎？
├─ 是 → 使用 is/has/can/should 前綴
└─ 否 → 是函式嗎？
├─ 是 → 使用動詞片語（動作）
└─ 否 → 是類別嗎？
├─ 是 → 使用名詞（PascalCase）
└─ 否 → 是常數嗎？
├─ 是 → 使用 UPPER_SNAKE_CASE
└─ 否 → 使用描述性名詞（camelCase/snake_case）
備註
- 清晰度優先於簡潔
- 上下文很重要（迴圈計數器可以是
i、j） - 眾所周知的縮寫可以接受（
html、api、url、id） - 專案內的一致性比完美的命名更重要
- 隨著理解提升，重新命名
- 使用 IDE 重新命名重構以安全更新所有參考
