前端开发命名规范

前言

优秀的代码往往是最通俗易懂的代码，在于它的易于维护。在开发过程中，变量/方法优秀的命名往往有助于理解该变量/方法的用途，起到命名即注释的作用。而糟糕的命名往往会让人摸不着头脑。为了提高代码的可维护性，我们需要更优雅的命名方式。

一. 常见命名种类

目前收集到的常见的命名方式主要有以下4种：

• 驼峰命名法（camelCase）

首字母小写，从第二个单词开始首字母大写，例如：myProjectFolder

• 帕斯卡命名法（PascalCase）

也成为“大驼峰命名法”，每个单词的首字母都大写，例如：MyProjectFolder

• 连字符命名法（kebab-case）

每个单词之间使用连字符（-）连接，例如：my-project-folder

• 蛇形命名法（camelCase）

每个单词之间使用下划线连接，例如：my_project_folder

当然还有其它的不常见命名方式，例如：大写蛇形命名法（一般用于常量命名，MAX_VALUE等），匈牙利命名法（在每个变量名的前面加上描述变量类型的前缀，strName等）。。。

首先要说，没有绝对的正确命名方式。不同的命名方式由使用该语言的社区群体来规定，使用哪种命名方式通常取决于团队的偏好、项目的要求以及所使用的编程语言的规范。

二、通用规则

1. 有意义

起一个有意义的变量名这条相信绝大多数开发者都能做到，即变量名有实际的指代意义，在此不再赘述。

2. 指代具体

命名时需要使其更加具体详尽，可以具体到所在的模块，或者能表达出其逻辑/功能。

/* bad */
.title {}
/* good */
.head-title {}

// bad
const info;
// good
const userInfo;

3. 遵循传统

无论是CSS、JavaScript、还是文件的命名，都有一些约定俗成的惯例和规范，我们只需遵循即可。

4. 约定规范

命名的规则有很多种，没有高低之分，只有相对合适，没有绝对完美的规则。通常为了维持项目的风格统一，通常在一个项目中，相同种类的规则只选取一种。毕竟规范也只是一种工具，运用规范的根本目的是为了更好的开发和维护，太过复杂的规范反而会阻碍正常开发。因之，在项目启动前，在技术栈选取后就应当进行规范的约定，这个过程是团队意见的整合，毕竟规范是要靠团队成员的相互配合。

四、CSS 中的命名

1. 划分原则

CSS中的类名根据其职责可以分为公共类名和自定义类名。其中公共类名又可以分为常见类名（一般是约定俗成）和工具类名。

2. 常见类名

下面整理了一些常见的 css类名 供大家参考：

CSS类名	说明
布局
layout	布局容器
wrapper/wrap	控制布局宽度的外围容器
header/head/hd	头部/顶部
main/bd	主体部分
footer/foot/ft	底部
sidebar	侧边栏
容器
banner	广告栏
content	内容部分
copyright	版权
list	列表
menu/submenu	菜单/二级菜单
nav/subnav	导航栏/二级导航
组件/细节
arrow	箭头
btn	按钮
download	下载
logo	徽标
message/msg	信息
news	新闻
product	产品
search	搜索
status	状态
summary	摘要
tab	标签页
tag	标签
text/txt	文本
tip	提示
title/subtitle	标题/二级标题
尺寸
large	大
middle	中等
small	小
mini	迷你
位置
top/right/bottom/left	上/右/下/左
关系
first	第一个
last	最后一个
prev	上一个
current	当前项
next	下一个
forward	向前
back	向后
状态
primary	主要
info	提示信息
success	成功
warning	一般警告
danger/error	严重警告/错误警告
link	文字链接
plain/ghost	按钮是否镂空
light	亮模式
dark	暗模式
disabled	禁用
active	激活
checked	选中
loading	加载中

3. 自定义类名

自定义类名一般以短横线“-”或者下划线“_”中的一种作为单词间分割，通常不使用驼峰命名，以此区别于变量。在项目中通常使用 scss、less 来进行样式书写，大大降低了类名重复引发的样式问题。因此我们只需要关注一个模块的外层容器类名。通常采用 模块名称-修饰名称 的命名方式。

三、JavaScript 中的命名

1. 划分原则

在JavaScript中，我们可以遵循小驼峰式命名和大驼峰式命名的规则。例如，使用firstName和lastName来表示名字的首字母大写。同时，为了更好地描述变量和函数的功能，我们可以选择使用动词前缀+名词修饰的方式，例如calculateTotal来表示计算总数、handleClick表示处理点击事件、setUser表示设置更新信息等。

2. 命名单词选择

一般情况下，变量/函数的命名采用动词前缀+名词修饰。

前缀	说明
变量
can	是否可以执行某操作
is	是否xxx
has	是否有xxx
函数
calc	计算
change	改变
fetch/get	获取（数据)
handle	操作
judge	判断
set	设置

3. 命名约定最佳实践

1. 变量的命名约定

JavaScript 变量名称是区分大小写的，大写和小写字母是不同的。比如：

let DogName = 'Scooby-Doo';
let dogName = 'Droopy';
let DOGNAME = 'Odie';
console.log(DogName);   // "Scooby-Doo"
console.log(dogName);   // "Droopy"
console.log(DOGNAME);   // "Odie"

但是，最推荐的声明 JavaScript 变量的方法是使用驼峰式变量名。我们可以对JavaScript 所有类型的变量使用驼峰式命名约定，这样就不会相同命名的变量。

// bad
let dogname = 'Droopy'; 
// bad
let dog_name = 'Droopy'; 
// bad
let DOGNAME = 'Droopy'; 
// bad
let DOG_NAME = 'Droopy'; 
// good
let dogName = 'Droopy';

变量的名称应该是不言自明的，并描述了储存的值。例如，如果需要一个变量来储存狗的名字，应该使用 dogName 而不是 Name，因为 dogNam 更有意义：

// bad
let d = 'Droopy';
// bad
let name = 'Droopy';
// good
let dogName = 'Droopy';

2. 布尔值的命名约定

当定义布尔类型的变量时，应该使用is或者has作为变量的前缀。例如，如果需要一个变量来检查狗是否有主任，应该使用 hasOwner 来最为变量名：

// bad
let bark = false;
// good
let isBark = false;

// bad
let ideal = true;
// good
let areIdeal = true;

// bad
let owner = true;
// good
let hasOwner = true;

3. 函数的命名约定

JavaScript 中函数的名称也是区分大小写的。因为在声明函数时，推荐使用驼峰式方法来命名函数。

除此之外，推荐使用描述性名词和动词来作为前缀。例如 query查询数据，send发送数据，宾语代表当前获取的目标对象。如果声明一个函数来获取名称，例如 queryUsers获取用户集合，saveUserInfo保存用户信息，getName获取名称

// bad
function name(dogName, ownerName) { 
  return '${dogName} ${ownerName}';
}
function productList() { // TODO }

// good
function getName(dogName, ownerName) { 
  return '${dogName} ${ownerName}';
}
function queryProductList() { // TODO }

4. 常量的命名约定

JavaScript 中的常量和变量是一样的，都区分大小写，在定义常量时，推荐使用大写，因为它们是不变的变量。

• 普通变量(number, string, date)

• 布尔类型：需要一个标识变量含义的前缀，比如has, is, wether, can, should等

• 数组/集合等复数形式：最好以s或list等能够标识复数形式的后缀结尾，标识当前变量是复数形式，提高可读性

// bad
let visited = false;

// good
const LEG = 4;
const TAIL = 1;
const MOVABLE = LEG + TAIL;
let isVisited = false;

如果变量声明名称中包含多个单词，就应该使用 UPPER_SNAKE_CASE。

const DAYS_UNTIL_TOMORROW = 1;

5. 类的命名约定

JavaScript 中类的命名约定规则与函数非常相似，推荐使用描述性的名称来描述类的功能。 ​

函数名和类名之间的主要区别在于类名要使用大写开头：

class DogCartoon { 
  constructor(dogName, ownerName) { 
    this.dogName = dogName; 
    this.ownerName = ownerName; 
  }
}

const cartoon = new DogCartoon('Scooby-Doo', 'Shaggy');

6. 组件的命名规则

JavaScript 组件广泛应用于React、Vue等前端框架中。组件的命名建议与类保持一致，Vue在单文件组件中推荐使用 帕斯卡命名法（PascalCase） 来命名组件名，因为可以和原生的HTML做出区分，并且可以使用“/>”的方式来关闭标签；

在单文件组件中，在 <template> 中使用注册的组件时，无论是使用 帕斯卡命名法（PascalCase） 还是 连字符命名法（kebab-case） 的形式都可以，Vue会自动处理命名转换，都转换成 帕斯卡命名法（PascalCase） 形式。（总之，推荐文件名都使用 帕斯卡命名法（PascalCase） 形式，在 <template> 中使用时用 连字符命名法（kebab-case） 方式）

// bad
function dogCartoon(roles) { 
  return ( 
    <div> 
      <span> Dog Name: { roles.dogName } </span> 
      <span> Owner Name: { roles.ownerName } </span> 
    </div> 
  );
} 

// good
function DogCartoon(roles) { 
  return ( 
    <div> 
      <span> Dog Name: { roles.dogName } </span> 
      <span> Owner Name: { roles.ownerName } </span> 
    </div> 
  );
}

由于组件的命名开头字母是大写，因此在使用时，就很容易和HTML、属性值等区分开来：

<div> 
  <DogCartoon 
    roles={{ dogName: 'Scooby-Doo', ownerName: 'Shaggy' }} 
  />
</div>

7. 方法的命名约定

这里说的方法指的是类中方法，在 JavaScript 中，类的方法和函数的结构是非常类似的，因此，命名约定规则也是一样的。 ​

推荐需要使用驼峰式方法来声明 JavaScript 方法，并使用动词作为前缀，使方法名称更有意义：

class DogCartoon {
  constructor(dogName, ownerName) { 
    this.dogName = dogName; 
    this.ownerName = ownerName; 
  }

  getName() { 
    return '${this.dogName} ${this.ownerName}'; 
  }
}

const cartoon= new DogCartoon('Scooby-Doo', 'Shaggy');

console.log(cartoon.getName());   // "Scooby-Doo Shaggy"

8. 私有函数的命名约定

下划线 (_) 在 MySQL 和 PHP 等语言中广泛用于定义变量、函数和方法。但在 JavaScript 中，下划线用于表示私有变量或函数。 ​

例如，有一个私有函数名 toonName，则可以通过添加下划线作为前缀 (_toonName) 来将其表示为私有函数。

class DogCartoon { 
  constructor(dogName, ownerName) { 
    this.dogName = dogName; 
    this.ownerName = ownerName; 
    this.name = _toonName(dogName, ownerName); 
  } 
  _toonName(dogName, ownerName) { 
    return `${dogName} ${ownerName}`; 
  } 
}

const cartoon = new DodCartoon('Scooby-Doo', 'Shaggy'); 

// good
const name = cartoon.name;
console.log(name);   // "Scooby-Doo Shaggy" 

// bad
name =cartoon._toonName(cartoon.dogName, cartoon.ownerName);
console.log(name);   // "Scooby-Doo Shaggy"

9. 全局变量的命名约定

对于 JavaScript 全局变量，没有特定的命名标准。建议对可变全局变量使用驼峰式大小写的方式，对不可变全局对象使用大写。

10. 文件名的命名约定

大多数 Web 服务器（Apache、Unix）在处理文件时都区分大小写。例如，flower.jpg 和 Flower.jpg 是不一样的。 ​

但是，如果从不区分大小写的服务器切换到区分大小写的服务器，即使是一个小错误也可能导致网站崩溃。 ​

因此，尽管它们是支持区分大小写的，建议在所有服务器中还是使用小写来命名文件。

小结

代码规范并不应该成为限制开发的束缚，我们的主要精力应该集中在项目的核心业务逻辑上。代码规范应该是为了更好地开发和维护代码而存在的工具，而不是阻碍开发的障碍。因此，我们应该持之以恒地在优化代码的过程中，逐步地遵循规范并不断改进。

总而言之，代码规范是为了提高代码质量和开发效率而存在的工具，我们应该在开发过程中不断优化和调整，始终保持学习和进步的态度，为构建高质量的软件而努力。只有持之以恒的追求，我们才能在优化代码的道路上越走越远！