命名规范与原则

前言

任何事务都有自身名字，也可以说名字是任何事务的属性之一。我们常说这个或那个名字取得好，那好在哪里呢？在我看来，名字是快速认识和了解一个事务最直接的方式。

在《代码整洁之道》这本书中告诉我们，一个有意义的命名到底有多么的重要。作为一名普普通通的码农，怎么样才能让别人一眼就能知道你的代码，那就需要学会去规范自身的代码命名管理。

命名原则

由于历史的驱动下，英文作为全球性通用语言。很多的事务都潜移默化得用英文去表示。

使用正确的词汇

描述

在我们的项目或代码中，尽可能使用正确的英文单词，不要拼写错误。如果英文不好的小伙伴，可以上网搜索进行纠正。

示例

// 坏的clound
// 好的cloud

使用具体的词汇

描述

因为我们项目或代码常常是与业务挂钩，所以非必要情况下，尽可能别把词汇定得太广泛，最好能够聚焦到某一个具体的业务块。

示例

// 坏的datainfo
// 好的userDatauserInfo

注意组合词汇定义方向

描述

我们习惯的阅读方式是从左往右，人通常对映入眼帘的第一个东西印象深刻。

示例

// 坏的dataUserinfoUser
// 好的userDatauserInfo

禁止创造或虚构词汇

描述

主要表现为：使用拼音或不能友好识别的词汇、使用自己创造的缩写等等

尽可能少用拼音，因为很多开发软件或其他人并不认识。

尽可能不要自己创造缩写，可以先查找下词汇本身是否有专业缩写形式。虽然看起来简短，但很难让人一下子就理解。

示例

// 坏的fangfa
// 好的function

使用对仗词汇

描述

示例

open/closemin/maxshow/hide...

命名规范

项目命名

描述

• 全部采用小写

• 采用串行命名法[^1] 或 蛇形命名法[^2]

示例

方式一：串行命名法

my-project

方式二：蛇形命名法

my_project

目录命名

指文件夹、层级结构

描述

• 采用小写串行命名法（推荐）[^1]

• 采用小写蛇形命名法（疑惑）

• 采用小写驼峰命名法（疑惑）

示例

方式一：小写串行命名法

- project - code-web - code-svr - code-pwa - ...

方式二：小写蛇形命名法

- project - code_web - code_svr - code_pwa

方式三：小写驼峰命名法

- project - codeWeb - codeSvr - codePwa

文件命名

描述

• 采用小驼峰命名法

示例

utils.jsstyle.cssgetName.py...

组件命名

描述

• 采用大驼峰命名法

示例

这里以 Vue 为例（index.vue 除外）

HelloWorld.vue...

路径命名

路由、路径、URL

描述

• 采用小驼峰命名法

示例

/get/list/get/userName

样式类命名

前端 css 样式类（Class）

描述

• 采用串行命名法[^1]

示例

.head-top{}.head-foot{}

注意

• 基于姓氏命名法（继承 + 外来）

• 在子孙模块数量可预测的情况下，继承祖先模块的命名前缀

• 当子孙模块超过 4 级或以上的情况下，可以考虑在祖先模块内具有识辨性的独立缩写作为新的子孙模块

图片命名

描述

• 采用串行命名法[^1] 或 蛇形命名法[^2]

推荐格式

业务（可选） + 功能类别（必选）+ 模块名称（可选） + 精度（可选）

图片业务: 广告（gg_）、学习（st_）等功能类别: 按钮（btn_）、背景（bg_）等模块名称: 头像（avatar_）、运动（spot_）等精度: @1x|@2x|@3x

示例

方式一：串行命名法

my-image.png

方式二：蛇形命名法

my_image.png

常量命名

描述

• 采用大写蛇形命名法[^2]

示例

MAX_NUM

变量命名

描述

• 全局变量，采用大写蛇形命名法

• 一般变量，采用小驼峰命名法和小写蛇形命名法

• 实例变量，以_开头的小写蛇形命名法

• 私有实例变量，以__开头（2 个下划线）的小写蛇形命名法

• 专有变量，以__开头，__结尾的小写蛇形命名法

示例

// 全局变量NAMEUSER_NAME
// 一般变量useruserName
// 实例变量_user_var_user_name_var
// 私有实例变量__user_var__user_name_var
// 专有变量__user____user_name__

对象类命名

类是名词，表示一个对象

描述

• 采用大驼峰命名法

示例

class Account ... {}class MyAccount ... {}

方法命名

方法或函数是动词或动宾短语，表示一个动作

描述

• 采用小驼峰命名法

• 采用小写蛇形命名法

示例

// 小驼峰命名法function get() {}function getName() {}
// 小写蛇形命名法function get() {}function get_name() {}

结语

我们可以使用一些工具来帮助命名，如果在几个单词之间摇摆不定，就去查看英英释义和例句。

[^1]: 串行命名法: 单词之间通过连字符“-”连接[^2]: 蛇形命名法: 单词之间通过下划线“_”连接[^3]: 驼峰命名法: 大驼峰为首字母大写，小驼峰为首字母小写