命名规则

命名规则的重要性

良好的命名规则能提升代码可读性、可维护性，减少团队协作中的沟通成本。JavaScript作为弱类型语言，命名规范尤为重要，它能弥补类型系统缺失带来的信息不足问题。

变量命名

基本规则

变量名采用小驼峰式命名（camelCase），由有意义的英文单词组成，避免缩写除非是广泛认可的：

// 好
const userList = [];
let isLoading = false;

// 差
const ul = [];  // 无意义缩写
let isld = false; // 晦涩缩写

布尔值命名

布尔变量应使用is、has、can等前缀：

const isVisible = true;
const hasPermission = false;
const canEdit = true;

特殊值命名

对于可能为null或undefined的变量，应明确表达其状态：

let selectedUser = null;  // 比 let user = null 更好
let currentPageIndex = undefined;

常量命名

普通常量

全大写字母加下划线（SCREAMING_SNAKE_CASE），用于不会改变的值：

const MAX_RETRY_COUNT = 3;
const API_TIMEOUT = 5000;

模块级常量

对于模块内使用的常量，仍使用小驼峰但用k前缀：

const kDefaultPageSize = 10;
const kCacheExpiryTime = 60 * 60 * 1000;

函数命名

常规函数

使用小驼峰，动词开头表明功能：

function getUserById(id) { /*...*/ }
function calculateTotalPrice() { /*...*/ }

返回值类型提示

通过名称暗示返回类型：

// 返回布尔值
function isValidEmail(email) { /*...*/ }

// 返回数组
function getActiveUsers() { /*...*/ }

回调函数

回调函数名称应包含on或handle前缀：

function onButtonClick() { /*...*/ }
function handleInputChange() { /*...*/ }

类命名

类与构造函数

使用大驼峰式（PascalCase）：

class UserModel {
  constructor() { /*...*/ }
}

function DatabaseConnection() { /*...*/ }

私有成员

ES2019+的私有字段使用#前缀：

class User {
  #passwordHash;
  
  constructor() {
    this.#passwordHash = '';
  }
}

文件与目录命名

文件命名

全部小写，多个单词用连字符连接：

user-service.js
date-utils.js

组件文件

React/Vue组件使用大驼峰：

UserProfile.vue
NotificationList.jsx

测试文件

与被测文件同名加.test后缀：

utils.js → utils.test.js
User.spec.js (Vue测试惯例)

特殊命名场景

事件命名

DOM事件全小写，自定义事件使用kebab-case：

element.addEventListener('click', handler);

// 自定义事件
emitter.emit('user-logged-in', data);

配置对象

配置项使用小驼峰，与API参数保持一致：

const chartConfig = {
  showLegend: true,
  animationDuration: 300
};

类型变量

TypeScript类型使用大驼峰：

interface UserProfile {
  id: number;
  name: string;
}

type HttpResponse<T> = {
  data: T;
  status: number;
};

命名长度控制

理想长度

变量名2-3个单词，函数名3-4个单词为佳：

// 刚好
const recentOrders = [];
function formatCurrencyValue() { /*...*/ }

// 过长
const listOfRecentlyPlacedCustomerOrders = []; 
function convertMonetaryValueToLocalCurrencyFormat() { /*...*/ }

上下文缩写

在明确上下文时可适当缩写：

// 在User类内部
class User {
  saveToDb() { /*...*/ }  // 比 saveToDatabase 更简洁
}

避免的命名实践

误导性名称

避免与语言特性冲突的名称：

// 不好
const new = getNewObject(); // 关键字冲突
let obj = {}; // 无意义

// 好
const freshInstance = getNewObject();
let userData = {};

单字母变量

仅在短生命周期作用域使用：

// 可接受
array.forEach((item) => { /*...*/ });

// 不好
function calculate(a, b, c) { /*...*/ }

下划线前缀

不再推荐用于"私有"成员（使用#代替）：

// 旧方式（不推荐）
class User {
  _internalId;
}

// 新方式
class User {
  #internalId;
}

命名一致性

项目统一

同一概念在整个项目中保持相同命名：

// 整个项目统一使用
let cartItems = [];  // 不是 shoppingCartProducts

// API响应统一处理
function handleApiError() { /*...*/ } // 不是 processHttpFailure

语言习惯

遵循JavaScript传统命名方式：

// jQuery风格（已过时）
const $container = $('#main');

// 现代标准
const mainContainer = document.querySelector('#main');

命名与重构

重命名信号

当出现这些情况时应考虑重命名：

// 1. 添加注释解释变量用途
const d; // 距离，单位：米 → 应改为 distanceInMeters

// 2. 函数内容与名称不符
function processData() {
  // 实际是验证数据
  return isValid;
}

安全重构技巧

利用IDE的重构功能：

// WebStorm/VS Code等支持：
// 右键 → Refactor → Rename
class BadName {
  // 改为 GoodName 时所有引用处自动更新
}