前端开发命名规范

一、文件规范

1、文件归档至约定的目录中

例如：css 分为两大类，通用类和业务类

基本样式库 /css/core
通用 ui 元素样式库 /css/lib
js 组件相关样式库 /css/ui

二、注释规范

1、文件顶部注释（推荐使用）

/* * @description: 中文说明 * @author: name * @update: name (2013-04-13 18:32) */

2、模块注释

/* module: module1 by 张三 */ … /* module: module2 by 张三 */

3、单行注释与多行注释

/* this is a short comment */

单行注释可以写在单独一行，也可以写在行尾，注释中的每一行长度不超过 40 个汉字，或者 80 个英文字符。

/*
 * this is comment line 1.
 * this is comment line 2.
 */

多行注释必须写在单独行内

4、特殊注释

/* TODO: xxxx by name 2013-04-13 18:32 */
/* BUGFIX: xxxx by name 2012-04-13 18:32 */

5、区块注释

/* Header */ /* Footer */ /* Gallery */

对一个代码区块注释（可选），将样式语句分区块并在新行中对其注释。

三、命名规范

使用有意义的或通用的 ID 和 class 命名：ID 和 class 的命名应反映该元素的功能或使用通用名称，而不要用抽象的晦涩的命名。反映元素的使用目的是首选；使用通用名称代表该元素不表特定意义，与其同级元素无异，通常是用于辅助命名；使用功能性或通用的名称可以更适用于文档或模版变化的情况。

/* 不推荐: 无意义 */ #yee-1901 {}
/* 不推荐: 与样式相关 */ .button-green {}.clear {}
/* 推荐: 特殊性 */ #gallery {}#login {}.video {}
/* 推荐: 通用性 */ .aux {}.alt {}

常用命名（多记多查英文单词）：page、wrap、layout、header(head)、footer(foot、ft)、content(cont)、menu、nav、main、submain、sidebar(side)、logo、banner、title(tit)、popo(pop)、icon、note、btn、txt、iblock、window(win)、tips 等

ID 和 class 命名越简短越好，只要足够表达涵义。这样既有助于理解，也能提高代码效率。

/* 不推荐 */ #navigation {}.atr {}
/* 推荐 */ #nav {}.author {}

类型选择器避免同时使用标签、ID 和 class 作为定位一个元素选择器；从性能上考虑也应尽量减少选择器的层级。

/* 不推荐 */ul#example {}div.error {}
/* 推荐 */#example {}.error {}

命名时需要注意的点：
规则命名中，一律采用小写加中划线的方式，不允许使用大写字母或 _
命名避免使用中文拼音，应该采用更简明有语义的英文单词进行组合
命名注意缩写，但是不能盲目缩写，具体请参见常用的 CSS 命名规则
不允许通过 1、2、3 等序号进行命名
避免 class 与 id 重名
id 用于标识模块或页面的某一个父容器区域，名称必须唯一，不要随意新建 id
class 用于标识某一个类型的对象，命名必须言简意赅。
尽可能提高代码模块的复用，样式尽量用组合的方式
规则名称中不应该包含颜色（red/blue）、定位（left/right）等与具体显示效果相关的信息。应该用意义命名，而不是样式显示结果命名

class 类样式命名遵守 BEM 方式：

.page-headermain
.dialogcontent
.gallery-list–wrap
.thumbnail-image–info
.action__btn-group

1、命名风格

a.【强制】在代码中严禁使用拼音与中英文混合的方式，更不允许直接使用中文的方式

// 正例
taobao;
tmall;
shanghai;
coupons;

// 反例
yhq[优惠券];

b.【强制】类名使用大写驼峰命名法来表示，Typescript 中枚举值使用大写驼峰命名法表示

// 正例
class User {}
enum Color {Red = 1, Green, Blue}

// 反例
class user {}

c.【强制】常量名全部大写，单词间使用下划线隔开

// 正例
GOOGLE_MAP_TOKEN;

// 反例
TOKEN;

d.【建议】在 TypeScript 中，类型使用 Type 作后缀，接口使用 I 作为前缀

type PropsType = {};
interface ILoginProps {}

e.【建议】在 Vue 和 Angular 中，模板语法中所有组件名使用中线命名法，在 React 中使用大写驼峰命名法来表示

// Vue
<el-button type="text" @click="toDetail">详情</el-button>
<custom-component a-prop="prop" />

// Angular
<nz-sider [nzWidth]="200" style="background:#fff"></nz-sider>

// React
<SelectPicture data={this.images} />

f.【推荐】统一使用中线命名法来命名目录

|-- page-header
|   |-- PageHeader.vue

g.【强制】在服务名上使用 Service 后缀

class UserService {}

h.【建议】组件文件名采用大写驼峰命名方式

// Vue
User.vue;

// React
User.jsx;

i.【建议】在 React 中使用目录名称作为组件名，在目录内容直接使用index作为入口，在 Vue 中使用目录名作为组件及页面名

// Vue
|-- user-info
|  |-- UserInfo.vue

// React
|-- user-info
|   |-- index.jsx

2、函数及 js 数据类型命名

a.表示可见性、进行中的状态

解释：可见性在通常指页面中的元素、组件是否显示（或者组件挂载到 DOM 上，但并不可见）。进行中主要是说明某种状态是处于持续进行中。
推荐命名方式为 is + 动词（现在进行时）/形容词

{
  isShow: '是否显示',
  isVisible: '是否可见',
  isLoading: '是否处于加载中',
  isConnecting: '是否处于连接中',
  isValidating: '正在验证中',
  isRunning: '正在运行中',
  isListening: '正在监听中'
}

b.属性状态类

解释：通常用来描述实体（例如：HTML 标签、组件、对象）的功能属性，而且定法比较固定。

{
  disabled: '是否禁用',
  editable: '是否可编辑',
  clearable: '是否可清除',
  readonly: '只读',
  expandable: '是否可展开',
  checked: '是否选中',
  enumberable: '是否可枚举',
  iterable: '是否可迭代',
  clickable: '是否可点击',
  draggable: '是否可拖拽'
}

c.配置类、选项类

解释：主要是指组件功能的开启与关闭，功能属性的配置。

{
  withTab: '是否带选项卡',
  withoutTab: '不带选项卡',
  enableFilter: '开启过滤',
  allownCustomScale: '允许自定义缩放',
  shouldClear: '是否清除',
  canSelectItem: '是否能选中元素',
  noColon: '不显示label后面的冒号',
  checkJs: '检查Js',
  emitBOM: 'Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files.'
}

d.事件处理

{
  onSubmit: '提交表单',
  handleSizeChange: '处理分页页数改变',
  handlePageChange: '处理分页每页大小改变',
  onKeydown: '按下键'
}

e.异步处理

{
  getUsers: '获取用户列表',
  fetchToken: '取得Token',
  deleteUser: '删除用户',
  removeTag: '移除标签',
  updateUsrInfo: '更新用户信息',
  addUsr: '添加用户',
  createAccount: '创建账户'
}

命名主要围绕数据的增删查找来划分，获取数据通常是 getXx 和 fetchXx，在作者看来两者在使用上的区分在于 getXx 的数据来源不一定直接取自异步的原始数据，可能是加工处理后的，而 fetchXx 是直接拿的原始数据。当然在实际项目中并没有区分，看个人喜好。
deleteXx 主要用于数据删除，而 removeXx 在语义上是移除数据，通常情况数据是还存在的，只是没有显示或数据假删除。updateXx 是指数据更新操作，addXx 是在已有列表数据中添加新的子项、而 createXx 主要是创建新的实例，比如新建一个账户。

g.数据的加工

情形一：根据特定属性获取属性

这里可以参考 DOM 方法的命名，比如：getElememtById()、getElementsByTagName()、getElementsByClassName() 和 getElementsByName()，然后提炼出一个比较实用的模板：getXxByYy()。其中 Xx 可以是：element, item, option, data, selection, list, options 以及一些特定上下文的名字，比如：user(s), menu(s) 等。Yy 相对来说比较固定，经常用到的就是 id, index, key, value, selected, actived 等。
除了使用 get，还可以使用 query 和 fetch，但是需要注意和上面提到的异步数据处理作一个区分。

{
  getItemById: '根据ID获取数据元素',
  getItemsBySelected: '根据传入的已选列表ID来获取列表全部数据',
  queryUserByUid: '根据UID查询用户'
}

情形二：格式化数据

这里的格式化操作包括排序、调整数据结构、过滤数据、添加属性。命名通常使用 formatXx, convertXx, inverseXx, toggleXx, parseXx, flatXx, 也可以结合数组的一些操作方法来命名，比如 sliceXx, substrXx, spliceXx, sortXx, joinXx 等来命名。

{
  formatDate: '格式化日期',
  convertCurrency: '转换货币单位',
  inverseList: '反转数据列表',
  toggleAllSelected: '切换所有已选择数据状态',
  parseXml: '解析XML数据',
  flatSelect: '展开选择数据',
  sortByDesc: '按降序排序'
}

四、常用英文词汇

1、代码常用词汇

动词

on: 监听、正在进行中
get: 取
set: 设置
fetch: 获取
find: 查找
add: 添加
create: 创建
remove: 移除
delete: 删除
update: 更新
upgrade: 升级
downgrade: 使降级
sync: 同步
toggle: 切换
pull: 拉
push: 推
show: 显示
hide: 隐藏
resolve: 解析；分解
parse: 解析
lock: 锁定
link: 连接
merge: 合并
close: 关闭
clone: 克隆
clear: 清除
format: 格式化
convert: 转变
cancel: 取消
accept: 承认；同意
check: 检查，核对
concat: 合并数组、字符串
join: 合并
split: 分开
spread: 展开
search: 搜索
sort: 排序
assign: 分配，指定
handle: 处理
trigger: 触发
login: 登入
logout: 登出
register: 注册
sign: 签名
throw: 抛出
load: 加载
preload: 加载
copy: 复制
paste: 粘贴
connect: 连接
change: 改变
select: 选择
validate: 验证
submit: 表单提交
commit: 提交
match: 匹配
scroll: 滚动
write: 写
read: 读
enable: 启用
disable: 禁用
limit: 限制
bootstrap: 启动
init: 初始化
install: 加载
upload: 上传
inject: 注入
provide: 提供
exit: 退出
access: 访问
flush: 刷新/使暴露
refresh: 刷新
release: 发布
preview: 预览；试映
publish: 出版；发行
navigate: 导航；浏览
redirect: 重定向
back: 返回
switch: 切换
launch: 加载
browse/visit: 浏览
append: 追加
insert: 插入
swap: 交换
map: 遍历
extract: 提取；选取
provide: 提供
inject: 注入
observe: 观察
render: 渲染
debug: 调试
align: 对齐
popup: 弹出
transfer: 转让、迁移
attach: 附加
build: 构建
diagnose: 诊断，断定
ignore: 忽略
deploy: 部署；展开
send/sent: 送；寄出
defer: 推迟
delegate: 委托
destroy: 销毁
dispatch: 派发；分派
trace: 追踪

名词

avatar: 头像
brand: 品牌
record: 记录
issue: 问题
project: 项目
repo(repository): 仓库；知识库
ecosystem: 生态系统
assets: 资产
resource: 资源
toolkit: 工具包、工具箱
workbench: 工作台
item: 项目；条款
option: 选项
field: 字段
type: 类型
status: 状态
property: 属性
attribute: 特性
parameter/argument: 参数
length: 长度
size: 尺寸
shape: 形状
label: 标签
value: 值
view: 视图
page: 页面
env(envirnment): 环境
context: 上下文
count: 总数；计数
amount: 数量；数额
sum: 合计；金额
num(number): 号码
total: 总数
money: 钱；货币
filter: 过滤器
pipe: 管道
stream: 流
buffer: 缓冲器
comment: 评论
ref(reference): 引用
res(response): 响应
req(request): 请求
entity: 实体
event: 事件
setup 设置
prefix 前缀
suffix 后缀
wizard 小部件
model 模型
flag 标志
factory 工厂
service 服务
constant: 常量
var(iable): 变量
collection: 集合
array: 数组
raw: 原始值
platform 平台
capital: 大写字母
uppercase/lowercase: 大/小写
letter: 字母
entrance: 入口
path: 路径
route: 路由
router: 路由器
config: 配置
middleware: 中间件
success: 成功
error: 错误
fail(ure): 失败
frontend: 前端
backend: 后端
local: 本地
sever: 服务器
production: 线上；产品
border: 边框
outline: 轮廓
precision: 精度
separator: 分隔符
mask: 遮罩
metadata: 元数据
location: 位置
sandbox: 沙箱
scope: 作用域
queue: 队列
heap: 堆
notice: 通知
bubble: 气泡
hooks: 钩子
cell: 单元格
row: 行
column: 列
group: 组
cursor: 游标
pattern: 模式
abstract: 抽象
compose: 复合；并集
callback: 回调函数
priority: 优先级
grade/rank/hierarchy 等级、层级
table,chart, graph, diagram: 表格，图表，曲线图，图表
system: 系统、体系
guards: 保障、守卫
segment/fragment: 片段、碎片
shaking: 抖动
mix: 混淆
dependence: 依赖
injection: 注入
markup: 标记
email: 电子邮件
version: 版本
detail: 详情
stub: 存根
score: 成绩
breakpoint: 断点
record: 记录
pointer: 指针
thumbnail: 缩略图
gallery: 画廊
viewport: 视口
strategy: 策略
outlet: 出口
inlet: 入口
gist: 主旨；要点；依据
licence: 许可证
copyright: 版权
order: 命令
input: 输入
output: 输出
effect: 影响；效果；作用
position: 位置
corner: 角落
animation: 动画
dot: 点
palette: 调色板；颜料
album: 相册
photo: 照片
host: 主机
session: 会话
cookie: 饼干；小甜点
domain: 域名
certificates: 证书
coercion: 强制
payload: 载物
thread: 线程
process: 进程
timestamp: 时间缀
conflicts: 冲突
terminal: 终端
portrait: 肖像
auxiliary: 附属物
backup: 备份
bitmap: 位图
breakpoint: 断点
concurrency: 并发
lock: 锁
digest: 摘要
exception: 异常
genericity: 泛型
handle: 句柄
macro: 宏
manifest: 清单
modifier: 修饰字；修饰符
override: 覆写
overload: 重载
procedure: 过程
protocol: 协议
recursion: 递归
marquee: 跑马灯

形容词

native: 原生的
hybrid: 混合的
basic: 基础的
complex: 复杂的
empty: 空的
online: 在线的
offline: 离线的
public: 公共的
private: 私有的
static: 静态的
dynamic: 动态的
shared: 共享的
safe: 安全的
relative: 相对的
absolute: 绝对的
original: 原始的
infinite: 无限的
partial: 局部的
ascending: 按升序
descending: 按降序
primary: 原始的，第一的
secondary: 第二的
tertiary: 第三的
deprecated: 弃用的
concrete: 具体的
abstract: 抽象的
explicit: 显示的；明确的
implicit: 含蓄的；暗示的
mutable: 可变的

2、业务常用词汇

电商

coupons: 优惠券
couponsCode: 优惠码
discount: 折扣
points: 积分
memeber: 会员
vip: 会员
membership: 会员
delivery: 运费
domain: 域名
dashboard: 仪表盘
store: 门店
shop: 店铺
product: 产品
goods: 商品
order: 订单
setting: 设置
manager: 管理
channel: 渠道
notFound: 404 页面
feedback: 反馈
scratch: 刮刮卡
client: 客户端
market: 市场
promotion: 促销
popularize: 推广
tool: 工具
banner: 广告
friendlink：友情链接
partner： 合作伙伴
vote: 投票