标点符号使用规范
本规范适用于文档、代码注释、提交信息、PR 描述及 Issue 内容中的标点符号使用，不约束代码字符串字面量内部的标点。
1. 句末标点
Section titled “1. 句末标点”1.1 句号
Section titled “1.1 句号”中文文档使用全角句号（。）结束完整句子。
- 标题、表格单元格内容、短语式列表项不加句号。
- 列表项为完整句子时加句号；为短语时省略句号。列表内所有项保持一致。
<!-- bad — 标题后加句号 -->
## 概述。
<!-- good -->
## 概述<!-- bad — 同一列表中风格不一致 -->
- 检查输入合法性。- 运行测试套件- 输出报告。
<!-- good — 全部为短语，不加句号 -->
- 检查输入合法性- 运行测试套件- 输出报告
<!-- good — 全部为完整句子，加句号 -->
- 本步骤检查输入合法性。- 本步骤运行测试套件。- 本步骤输出报告。1.2 感叹号与问号
Section titled “1.2 感叹号与问号”技术文档中避免使用感叹号（！），仅在真实的警告或危险提示中使用。
问号（？）仅用于 FAQ 或显式疑问句。
2.1 顿号与逗号
Section titled “2.1 顿号与逗号”并列的名词性短语使用顿号（、）；并列的从句或较长短语使用逗号（，）：
<!-- bad — 短语并列用逗号 -->函数接受名称，类型，值三个参数。
<!-- good — 短语并列用顿号 -->函数接受名称、类型、值三个参数。
<!-- good — 从句并列用逗号 -->如果参数为空，则返回默认值，否则抛出错误。2.2 避免逗号粘连
Section titled “2.2 避免逗号粘连”不要用逗号连接两个独立的完整句子，应使用句号分隔：
<!-- bad -->请求成功，响应体包含用户对象。
<!-- good -->请求成功。响应体包含用户对象。3. 冒号与分号
Section titled “3. 冒号与分号”3.1 冒号
Section titled “3.1 冒号”冒号（：）用于引出列表、解释或示例。冒号前必须是完整的引导句：
<!-- bad — 引导词不完整 -->支持的格式：
- JSON- YAML
<!-- good -->支持以下格式：
- JSON- YAML3.2 分号
Section titled “3.2 分号”中文文档中分号（；）用于分隔关系密切、结构对等的并列句。不确定时优先使用句号：
<!-- 可用 -->第一轮解析 AST；第二轮执行类型检查。
<!-- 同样可用 -->第一轮解析 AST。第二轮执行类型检查。不要用分号分隔列表项，改用项目符号列表。
4.1 直引号与弯引号
Section titled “4.1 直引号与弯引号”中文文档中使用弯引号（“…”、‘…’）引用文本、术语或直接引语。外层用双引号，内层用单引号：
<!-- good -->所谓"幂等"，指的是多次调用产生相同结果。不要用引号高亮技术术语，应使用反引号：
<!-- bad -->将"timeout"字段设为 0 可关闭限制。
<!-- good -->将 `timeout` 字段设为 `0` 可关闭限制。4.2 标点与引号的位置
Section titled “4.2 标点与引号的位置”引号仅引用部分内容时，句末点号置于引号外部；引用完整句子时，句末点号置于引号内部：
<!-- good — 引用部分内容，点号在引号外 -->错误信息为“连接被拒绝”。点击“保存”，然后关闭对话框。
<!-- good — 引用完整句子，点号在引号内 -->古话说：“三人行，必有我师焉。”5.1 圆括号
Section titled “5.1 圆括号”用圆括号（）补充说明去掉后不影响句意的内容。括号内容应简洁：
<!-- good -->当 ID 无效时，接口返回 404 状态码（资源不存在）。括号内为完整句子时，句号置于括号内：
<!-- good -->详见配置参考文档。（完整选项列表见附录 A。）5.2 方括号
Section titled “5.2 方括号”方括号 [] 仅用于命令语法中表示可选参数，不用于正文叙述：
<!-- good -->git commit -m "<消息>" [--no-verify]6. 连字符与破折号
Section titled “6. 连字符与破折号”6.1 连字符
Section titled “6.1 连字符”中文中用中点（·）连接外文人名，用连字符（-）连接英文复合词或技术术语中的分隔：
<!-- good -->kebab-case 命名风格TypeScript 的 read-only 字段6.2 破折号
Section titled “6.2 破折号”中文破折号为双横线（——），用于解释说明或话题转换，两侧不加空格：
<!-- good -->该函数返回 null——而非 undefined——当值缺失时。不要用两个连字符（—）代替破折号。
7. 省略号
Section titled “7. 省略号”省略号（……）仅用于引用中省略内容，或代码示例中省略的代码行。不要用省略号表达模糊或随意：
<!-- bad -->你可以配置各种选项……
<!-- good -->函数签名为：fn(name, type, ...args)代码示例中用注释表示省略行，不用省略号：
// goodfunction foo() { // ...}8. 全角与半角
Section titled “8. 全角与半角”8.1 全角标点的使用场景
Section titled “8.1 全角标点的使用场景”中文语境中使用全角标点：
| 符号 | 全角 | 半角 |
|---|---|---|
| 句号 | 。 | . |
| 逗号 | ， | , |
| 顿号 | 、 | , |
| 冒号 | ： | : |
| 分号 | ； | ; |
| 感叹号 | ！ | ! |
| 问号 | ？ | ? |
| 引号 | “…” ‘…’ | ”…” ’…’ |
| 括号 | （） | () |
| 破折号 | —— | — |
| 省略号 | …… | … |
8.2 半角标点的使用场景
Section titled “8.2 半角标点的使用场景”以下情况使用半角标点：
- 英文句子内部
- 代码、命令、文件路径
- 数字与单位之间（见第 9 节）
- Markdown 语法结构（如链接
[文字](url)、代码块等）
9. 技术写作约定
Section titled “9. 技术写作约定”9.1 行内代码
Section titled “9.1 行内代码”函数名、变量名、文件名、命令、配置值等技术内容一律用反引号包裹：
<!-- bad -->挂载后调用 render 函数。在配置文件中将 debug 设为 true。
<!-- good -->挂载后调用 `render` 函数。在配置文件中将 `debug` 设为 `true`。9.2 中英文混排间距
Section titled “9.2 中英文混排间距”中文与英文、数字之间加一个半角空格：
<!-- bad -->使用Node.js运行脚本，版本需≥18。
<!-- good -->使用 Node.js 运行脚本，版本需 ≥ 18。中文标点前后不加空格：
<!-- bad -->请求成功 ，响应体包含用户对象 。
<!-- good -->请求成功，响应体包含用户对象。9.3 数字与单位
Section titled “9.3 数字与单位”数字与单位之间加半角空格，百分号除外：
<!-- good -->16 MB、100 ms、80%超时时间为 30 秒。