JS变量命名核心是语义清晰、自解释，需遵守语法底线（字母/数字/_/$开头非数）、大小写敏感、禁用关键字、小驼峰、布尔加is/has/can、常量全大写下划线、禁用模糊词；团队靠ESLint、NAMING.md文档、Code Review三件套落地。
JS 变量命名规范的核心不是背规则，而是让名字“自己说话”——别人看一眼就知道它存什么、在哪用、能不能改。团队落地的关键也不在强制统一，而在建立可检查、可讨论、可迭代的共识机制。
基础命名规则必须守住底线
这些是语法+协作的硬性前提，不满足就容易出错或引发歧义：
-
只用字母、数字、下划线（_）、美元符（$），且首字符不能是数字（
let 1user报错）； -
严格区分大小写：
userName、UserName、USERNAME是三个变量； -
禁用关键字和保留字：比如
class、let、default、package不能当变量名； -
默认用小驼峰（camelCase）：如
isModalOpen、userProfileData、maxRetryCount； -
布尔值加
is/has/can前缀：如isActive、hasPermission、canEdit，一眼识别用途； -
常量全大写下划线：如
API_TIMEOUT_MS、DEFAULT_PAGE_SIZE，配合const声明； -
避免模糊词：不用
data、info、temp、val，优先用userPreferences、orderStatus、retryDelayMs。
语义清晰比长度更关键
名字不是越短越好，而是“刚好够懂”。缩写只在上下文明确、团队公认时才用：
- 当前用户姓名 →
currentUserName（官方推荐），不是name（太泛）或curUName（自造缩写）； - 我们所在的星球 →
ourPlanetName（强调归属），不是planet（歧义）或earthName（硬编码，不具扩展性）； - API 响应错误信息 →
apiResponseError比err或resErr更稳妥； - 若变量作用域极小（如单个 for 循环内），
i、j可接受；但函数参数或对象属性一律用完整名，如startIndex而非si。
团队落地靠三件套：工具 + 文档 + 习惯
光靠口头约定很难持久，需要轻量但有效的支撑：
-
ESLint 配置固化规则：启用
camelcase、no-unused-vars、id-length（设最小长度为2）等规则，CI 中失败即阻断； -
命名决策文档（不是长篇大论）：维护一个简短的
NAMING.md，只列高频场景示例，比如：
✅ 推荐：isLoading、userRoleList、MAX_RETRY_ATTEMPTS
❌ 避免：loading（类型不明）、roles（缺上下文）、maxRetry（单位/类型缺失） - Code Review 明确命名项：把“变量名是否自解释”列为必查点，新人 PR 中第一次起名不当，不直接改，而是引导提问：“如果没看上下文，这个变量你猜它存什么？”；
-
编辑器补全友好：鼓励用稍长但结构清晰的名字（如
cartItemQuantity），现代编辑器能自动提示，反而比短名更快输入、更少出错。
特殊场景处理有章法
真实项目总有例外，关键是提前约定而不是临时发挥：
-
第三方 API 字段映射：保留原始命名（如
api_response_code），但用别名转成内部风格：const responseCode = apiData.api_response_code;； -
国际化 key 或 CSS 类名：允许用中划线（
user-profile-card），但 JS 变量仍走 camelCase，不混用； -
类型相关前缀（谨慎使用）：仅在 TypeScript 缺失或强类型需求明显时考虑，如
strUsername、numTimeoutMs，但优先用类型系统或 JSDoc 注释替代。
