# 中文命名规范

**Repository Path**: remyzane/zh-code-spec

## Basic Information

- **Project Name**: 中文命名规范
- **Description**: 中文代码命名规范
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-12-12
- **Last Updated**: 2026-05-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 中文命名规范

## 适用于

已使用中文命名或认同中文必将是国际通用语的研发团队。<br>
尤其适用于已养成英文命名习惯的开发者（按照文档可以无缝切换回中文命名）。

## 命名原则

**不泥古，不媚外；可读为先，效率为本；中文达意，西文取便**

## 可保留的字母符号

**技术标准/协议/格式名称**

XML, HTML, CSS, SQL, HTTP, HTTPS, TCP/IP, URL, URI, UUID, JWT, OAuth, API, Git, Docker, K8s, Linux

**简洁技术词**

id, index, key, value, len, err, ok, buf, ptr, ref, env

**中英混合命名**

不建议在中英文之间使用下划线（中英文边界清晰）<br>
要视觉对齐可以使用大写字母（英文为技术标准/协议/格式名称）<br>
要突出中文可以使用小写字母（英文作为前缀、后缀、标识符）<br>

## 类和实例

英文可以通过首字母大小写来区分类和实例，中文需要添加后缀来区分。<br>
（建议类和实例中文名相同，但类有字母后缀，实例没有）<br>
**具体类**建议后缀加「类」或大写字母，如 M（模型）、T（类型）、D (DTO)；<br>
**抽象类**可以加小写字母后缀，如：mx（Mixin）；<br>

## 复数对象

中文没有类似英文的单词层面的复数形式，名称中必须包含数据类型后缀（为了代码可读性和编码便捷性（避免个体和群体同名））。<br>
如果某类数据的名称已经约定俗成，则可以不添加类型后缀，如：待办清单、订单明细、键值对、键值映射、路由表。<br>
给类型为「元组」的对象命名，如果要加类型后缀，尽量用「元组」（已经约定俗成的除外，很多内容人们习惯了叫列表）

| 数据类型 | 通用后缀 |      定义                     |   示例                            |
| ------- | ----- | ----------------------------- | ------------------------- |
|  list	  |  列表  |  有序、可重复、动态增删的元素序列  |  商品列表、待办清单、订单明细  |
|  array  |  数组  |  同 list，但元素类型固定        | 颜色数组、用户ID数组 |
|  tuple  |  元组  |  同 list，但不能动态增删        |  版本号元组、坐标元组、键值对  |
|  set    |  集   |	 无序、元素唯一的数据集合        |   权限集、标签集    |
|  dict   |  字典  |  由键值对组成的映射结构         |  配置字典、键值映射、路由表  |
|  queue  |  队列  |  先进先出（FIFO）的线性数据结构  |  任务队列、消息队列  |
|  stack  |  栈   |  后进先出（LIFO）的线性数据结构  |  操作栈、函数调用栈  |

## 状态定义

英语使用固定句式和词态，状态命名比较简单，统一用：**is_xxx**。<br>

中文不建议使用「是否XXX」如：「if (是否弹出菜单) {}」 从名称看根本看不出到底是还是否。<br>
建议根据具体情况处理：

### 纯行为（动词）可根据词态

|   类别    |   推荐格式        |    示例                                             |
| -------- |  --------------- | --------------------------------------------- |
|  完成态	|    已xx	       |   已激活、已保存、已同步   |
|  进行态	|    xx中         |   加载中、上传中、处理中   |
|  否定态	|    未xx、非xx    |   未登录、未验证、非管理员   |
|  静态     |   直接用形容词	|   有效、就绪   |

**枚举状态**可使用「xx + 状态」命名，如：「const 任务状态: '进行中' | '已完成' = '进行中';」<br>
**一个事物不只一种状态时优先使用枚举状态**

### 行为加对象（动词+名词）使用倒置（名词+动词）

动作使用「动词 + 名词」如：<br>
把 **弹出菜单** 作为方法/函数名

布尔状态使用「名词 + 动词」，如：<br>
let **菜单弹出**: boolean = false; // if (菜单弹出) {} 」即可以表示菜单**要弹出**也可以表示菜单**已弹出**）<br>
*(适用于结果驱动 / 简单交互，如：普通 React、Vue 程序)*

状态对象使用「名词.动词 + 态」，如：<br>
let 菜单: { **弹出态**: boolean }; // if (菜单.弹出态) {} 」即可以表示菜单**要弹出**也可以表示菜单**已弹出**）<br>
*(适用于结果驱动 / 简单交互，如：普通 React、Vue 程序)*

枚举状态使用「名词 + 状态」（动词作为枚举值的组成部分），如：<br>
let **菜单状态**: '要弹出' | '已弹出';<br>
*(适用于过程驱动 / 复杂交互，如：弹出期间需要自行显示复杂特效)*<br>
**一个事物不只一种状态时优先使用枚举状态**

## 布尔前缀（中英对照）

|   英文    |     中文          |   使用场景       |   示例                            |
| -------- |  ---------------- | --------------- | --------------------------------- |
|  has	   |   有、没           |   拥有关系       |   有权限、没问题、有搞头    |
|  can	   |   能、不能	        |   能力/权限      |   能发射、能摧毁、不能更改    |
|  needs   |   需、无需	        |   客观需求       |   需更新、需验证、无需在意    |
|  should  |   建议、不建议      |   策略建议       |   建议D方案、不建议B方案   |

## 高频动词（中英对照）

|   英文    |    中文    |    使用场景                                             |
| -------- |  -------- | ----------------------------------------------------- |
|  get	   |    获取	|   返回值，无副作用   |
|  set	   |   	设置	|   赋值，可能触发校验   |
|  add	   |   	添加	|   向集合插入元素   |
|  remove  |   	移除	|   从集合删除元素   |
|  load	   |   	加载	|   从磁盘/数据库读入内存   |
|  save	   |   	保存	|   写入持久化存储   |
|  fetch   |   	拉取	|   从远程（API/网络）获取   |

## 具体命名规范

- **[数据库](数据库.md)** - 数据库对象命名规则

## 中文编程工具

- [VSCode 中文代码补全插件](https://marketplace.visualstudio.com/items?itemName=chinese.vscode-zh-completion)

## 规范中文命名，提升代码质量！ 🎉