the-art-of-naming

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

The Art of Naming

命名的艺术

Naming things is hard. This guide provides a structured methodology for naming variables, functions, classes, interfaces, and everything in between — producing code that is self-documenting, consistent, and readable.

命名是一件很难的事。本指南为变量、函数、类、接口及所有代码元素的命名提供了一套结构化方法，帮助你写出自解释、统一且易读的代码。

When to Apply

适用场景

Reference these guidelines when:

Naming new variables, functions, classes, interfaces, or types
Reviewing code for naming consistency
Refactoring code to improve readability
Setting up linting rules for a new project
Onboarding new team members to the codebase conventions

在以下场景参考这些指南：

为新变量、函数、类、接口或类型命名时
评审代码的命名一致性时
重构代码以提升可读性时
为新项目配置lint规则时
向新团队成员同步代码库约定时

Core Principles

核心原则

S-I-D — Every name must be Short, Intuitive, and Descriptive
No Contractions —
```
onItemClick
```
, never
```
onItmClk
```
Correct Casing — camelCase for members, PascalCase for types, UPPER_CASE for constants
Meaningful Prefixes —
```
I
```
for interfaces,
```
_
```
for private,
```
is/has/should
```
for booleans

No Context Duplication —

MenuItem.handleClick()

, not

MenuItem.handleMenuItemClick()

Structured Patterns — P/HC/LC for variables, A/HC/LC for functions
Correct Action Verbs —
```
get
```
(sync),
```
fetch
```
(async),
```
remove
```
(collection),
```
delete
```
(permanent)

S-I-D — 每个命名都必须Short（简短）、Intuitive（直观）且Descriptive（具描述性）
禁止缩写 — 用
```
onItemClick
```
，永远不要用
```
onItmClk
```
正确的大小写规范 — 成员用camelCase，类型用PascalCase，常量用UPPER_CASE
有意义的前缀 — 接口加
```
I
```
前缀，私有成员加
```
_
```
前缀，布尔值加
```
is/has/should
```
前缀

禁止上下文冗余 — 用

MenuItem.handleClick()

，不要用

MenuItem.handleMenuItemClick()

结构化命名模式 — 变量采用P/HC/LC模式，函数采用A/HC/LC模式
正确的动作动词 —
```
get
```
（同步操作）、
```
fetch
```
（异步操作）、
```
remove
```
（移除集合元素）、
```
delete
```
（永久删除）

Rule Categories by Priority

按优先级划分的规则类别


naming-casing-convention
naming-sid
naming-prefix-convention
naming-boolean
naming-context-duplication
naming-function-pattern
naming-variable-pattern

Priority	Rule	Impact	File
1	Casing Convention	CRITICAL	`naming-casing-convention`
2	S-I-D + No Contractions	CRITICAL	`naming-sid`
3	Prefix Conventions	HIGH	`naming-prefix-convention`
4	Boolean Naming	HIGH	`naming-boolean`
5	Context Duplication	HIGH	`naming-context-duplication`
6	Function Naming (A/HC/LC)	HIGH	`naming-function-pattern`
7	Variable Naming (P/HC/LC)	MEDIUM	`naming-variable-pattern`


naming-casing-convention
naming-sid
naming-prefix-convention
naming-boolean
naming-context-duplication
naming-function-pattern
naming-variable-pattern

优先级	规则	影响程度	对应文件
1	大小写规范	严重	`naming-casing-convention`
2	S-I-D原则 + 禁止缩写	严重	`naming-sid`
3	前缀约定	高	`naming-prefix-convention`
4	布尔值命名	高	`naming-boolean`
5	上下文冗余	高	`naming-context-duplication`
6	函数命名（A/HC/LC模式）	高	`naming-function-pattern`
7	变量命名（P/HC/LC模式）	中等	`naming-variable-pattern`

Quick Reference

快速参考

1. Casing Convention (CRITICAL)

1. 大小写规范（严重级）

```
naming-casing-convention
```
- camelCase for variables/functions, PascalCase for classes/enums/types, UPPER_CASE for exported constants

```
naming-casing-convention
```
- 变量/函数用camelCase，类/枚举/类型用PascalCase，导出常量用UPPER_CASE

2. S-I-D + No Contractions (CRITICAL)

2. S-I-D原则 + 禁止缩写（严重级）

```
naming-sid
```
- Names must be Short, Intuitive, Descriptive — never use contractions

```
naming-sid
```
- 命名必须简短、直观、具描述性 — 永远不要使用缩写

3. Prefix Conventions (HIGH)

3. 前缀约定（高优先级）

```
naming-prefix-convention
```
-
```
I
```
for interfaces,
```
_
```
for private members,
```
T
```
/
```
R
```
/
```
U
```
/
```
V
```
/
```
K
```
for generics

```
naming-prefix-convention
```
- 接口加
```
I
```
前缀，私有成员加
```
_
```
前缀，泛型用
```
T
```
/
```
R
```
/
```
U
```
/
```
V
```
/
```
K
```
作为前缀

4. Boolean Naming (HIGH)

4. 布尔值命名（高优先级）

```
naming-boolean
```
- Prefix booleans with
```
is
```
/
```
has
```
/
```
should
```
/
```
can
```
, keep names positive

```
naming-boolean
```
- 布尔值加
```
is
```
/
```
has
```
/
```
should
```
/
```
can
```
前缀，保持命名表述为肯定形式

5. Context Duplication (HIGH)

5. 上下文冗余（高优先级）

```
naming-context-duplication
```
- Don't repeat class/component name in member names

```
naming-context-duplication
```
- 不要在成员命名中重复类/组件的名称

6. Function Naming (HIGH)

6. 函数命名（高优先级）

```
naming-function-pattern
```
- A/HC/LC pattern + correct action verbs (get/set/fetch/remove/delete/compose/handle)

```
naming-function-pattern
```
- 采用A/HC/LC模式 + 正确的动作动词（get/set/fetch/remove/delete/compose/handle）

7. Variable Naming (MEDIUM)

7. 变量命名（中优先级）

```
naming-variable-pattern
```
- P/HC/LC pattern for structured, predictable variable names

```
naming-variable-pattern
```
- 采用P/HC/LC模式保证变量命名结构化、可预测

How to Use

使用方式

Read individual rule files for detailed explanations and code examples:

rules/naming-casing-convention.md
rules/naming-sid.md
rules/naming-prefix-convention.md
rules/naming-boolean.md
rules/naming-context-duplication.md
rules/naming-function-pattern.md
rules/naming-variable-pattern.md

Each rule file contains:

Brief explanation of why it matters
Incorrect code examples with explanation
Correct code examples with explanation
Summary tables and references

阅读各规则文件获取详细说明和代码示例：

rules/naming-casing-convention.md
rules/naming-sid.md
rules/naming-prefix-convention.md
rules/naming-boolean.md
rules/naming-context-duplication.md
rules/naming-function-pattern.md
rules/naming-variable-pattern.md

每个规则文件包含：

规则重要性的简要说明
带解释的错误代码示例
带解释的正确代码示例
汇总表格和参考资料

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需查看所有规则展开的完整指南，参见：

AGENTS.md