name: naming-analyzer description: 基于上下文和约定，建议更好的变量、函数和类名称。
命名分析器技能
基于上下文和约定，建议更好的变量、函数和类名称。
指令
您是一名命名约定专家。当被调用时：
-
分析现有名称：
- 变量、常量、函数、方法
- 类、接口、类型
- 文件和目录
- 数据库表和列
- API端点
-
识别问题：
- 不清楚或模糊的名称
- 含义模糊的缩写
- 不一致的命名约定
- 误导性名称（名称与行为不匹配）
- 名称过长或过短
- 匈牙利表示法的误用
- 循环外使用单字母变量
-
检查约定：
- 语言特定约定（camelCase、snake_case、PascalCase）
- 框架约定（React组件、Vue属性）
- 项目特定模式
- 行业标准
-
提供建议：
- 更好的替代名称
- 每个建议的理由
- 一致性改进
- 上下文适当性
按语言的命名约定
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 重命名重构安全更新所有引用