标点符号使用规范

本规范适用于文档、代码注释、提交信息、PR 描述及 Issue 内容中的标点符号使用，不约束代码字符串字面量内部的标点。

---

1. 句末标点

1.1 句号

中文文档使用全角句号（。）结束完整句子。

• 标题、表格单元格内容、短语式列表项不加句号。
• 列表项为完整句子时加句号；为短语时省略句号。列表内所有项保持一致。

<!-- bad — 标题后加句号 -->

## 概述。

<!-- good -->

## 概述

<!-- bad — 同一列表中风格不一致 -->

- 检查输入合法性。
- 运行测试套件
- 输出报告。

<!-- good — 全部为短语，不加句号 -->

- 检查输入合法性
- 运行测试套件
- 输出报告

<!-- good — 全部为完整句子，加句号 -->

- 本步骤检查输入合法性。
- 本步骤运行测试套件。
- 本步骤输出报告。

1.2 感叹号与问号

技术文档中避免使用感叹号（！），仅在真实的警告或危险提示中使用。

问号（？）仅用于 FAQ 或显式疑问句。

---

2. 逗号

2.1 顿号与逗号

并列的名词性短语使用顿号（、）；并列的从句或较长短语使用逗号（，）：

<!-- bad — 短语并列用逗号 -->
函数接受名称，类型，值三个参数。

<!-- good — 短语并列用顿号 -->
函数接受名称、类型、值三个参数。

<!-- good — 从句并列用逗号 -->
如果参数为空，则返回默认值，否则抛出错误。

2.2 避免逗号粘连

不要用逗号连接两个独立的完整句子，应使用句号分隔：

<!-- bad -->
请求成功，响应体包含用户对象。

<!-- good -->
请求成功。响应体包含用户对象。

---

3. 冒号与分号

3.1 冒号

冒号（：）用于引出列表、解释或示例。冒号前必须是完整的引导句：

<!-- bad — 引导词不完整 -->
支持的格式：

- JSON
- YAML

<!-- good -->
支持以下格式：

- JSON
- YAML

3.2 分号

中文文档中分号（；）用于分隔关系密切、结构对等的并列句。不确定时优先使用句号：

<!-- 可用 -->
第一轮解析 AST；第二轮执行类型检查。

<!-- 同样可用 -->
第一轮解析 AST。第二轮执行类型检查。

不要用分号分隔列表项，改用项目符号列表。

---

4. 引号

4.1 直引号与弯引号

中文文档中使用弯引号（“…”、‘…’）引用文本、术语或直接引语。外层用双引号，内层用单引号：

<!-- good -->
所谓"幂等"，指的是多次调用产生相同结果。

不要用引号高亮技术术语，应使用反引号：

<!-- bad -->
将"timeout"字段设为 0 可关闭限制。

<!-- good -->
将 `timeout` 字段设为 `0` 可关闭限制。

4.2 标点与引号的位置

引号仅引用部分内容时，句末点号置于引号外部；引用完整句子时，句末点号置于引号内部：

<!-- good — 引用部分内容，点号在引号外 -->
错误信息为“连接被拒绝”。
点击“保存”，然后关闭对话框。

<!-- good — 引用完整句子，点号在引号内 -->
古话说：“三人行，必有我师焉。”

---

5. 括号

5.1 圆括号

用圆括号（）补充说明去掉后不影响句意的内容。括号内容应简洁：

<!-- good -->
当 ID 无效时，接口返回 404 状态码（资源不存在）。

括号内为完整句子时，句号置于括号内：

<!-- good -->
详见配置参考文档。（完整选项列表见附录 A。）

5.2 方括号

方括号 [] 仅用于命令语法中表示可选参数，不用于正文叙述：

<!-- good -->
git commit -m "<消息>" [--no-verify]

---

6. 连字符与破折号

6.1 连字符

中文中用中点（·）连接外文人名，用连字符（-）连接英文复合词或技术术语中的分隔：

<!-- good -->
kebab-case 命名风格
TypeScript 的 read-only 字段

6.2 破折号

中文破折号为双横线（——），用于解释说明或话题转换，两侧不加空格：

<!-- good -->
该函数返回 null——而非 undefined——当值缺失时。

不要用两个连字符（--）代替破折号。

---

7. 省略号

省略号（……）仅用于引用中省略内容，或代码示例中省略的代码行。不要用省略号表达模糊或随意：

<!-- bad -->
你可以配置各种选项……

<!-- good -->
函数签名为：fn(name, type, ...args)

代码示例中用注释表示省略行，不用省略号：

// good
function foo() {
  // ...
}

---

8. 全角与半角

8.1 全角标点的使用场景

中文语境中使用全角标点：

符号	全角	半角
句号	。	.
逗号	，	,
顿号	、	,
冒号	：	:
分号	；	;
感叹号	！	!
问号	？	?
引号	“…” ‘…’	"…" '…'
括号	（）	()
破折号	——	—
省略号	……	...

8.2 半角标点的使用场景

以下情况使用半角标点：

• 英文句子内部
• 代码、命令、文件路径
• 数字与单位之间（见第 9 节）
• Markdown 语法结构（如链接 [文字](url)、代码块等）

---

9. 技术写作约定

9.1 行内代码

函数名、变量名、文件名、命令、配置值等技术内容一律用反引号包裹：

<!-- bad -->
挂载后调用 render 函数。
在配置文件中将 debug 设为 true。

<!-- good -->
挂载后调用 `render` 函数。
在配置文件中将 `debug` 设为 `true`。

9.2 中英文混排间距

中文与英文、数字之间加一个半角空格：

<!-- bad -->
使用Node.js运行脚本，版本需≥18。

<!-- good -->
使用 Node.js 运行脚本，版本需 ≥ 18。

中文标点前后不加空格：

<!-- bad -->
请求成功 ，响应体包含用户对象 。

<!-- good -->
请求成功，响应体包含用户对象。

9.3 数字与单位

数字与单位之间加半角空格，百分号除外：

<!-- good -->
16 MB、100 ms、80%
超时时间为 30 秒。