| name | mcpp-docs-style |
| description | Use when writing or editing anything under docs/ (English or 简体中文), README files, or long-form design records — states the register mcpp documentation is written in (declarative, precise, professional), the constructions that are not admitted (question headings, conversational asides, internet slang, figurative jargon), and the bilingual parity rules. |
mcpp 文档风格规范
适用范围
docs/**(含 docs/zh/**)、README.md、.agents/docs/** 的对外部分。
代码注释与 commit message 不受本规范约束 —— 它们的读者、篇幅与目的都不同,
那里允许并鼓励叙述「为什么」以及实测过程。本规范约束的是面向用户的文档。
一、总原则
文档是参考资料,不是博客,也不是聊天记录。判据只有一条:
一位不认识作者、只想解决自己问题的工程师,能不能在最短时间内
拿到准确的事实,并且不会误以为某个说法比实际更随意或更绝对。
由此得到三条可执行的规则:陈述、精确、克制。
二、标题
标题一律是名词短语或陈述句,不使用疑问句、不使用口语片段。
疑问句标题把「读者已经知道自己在找什么」这个前提丢掉了 —— 目录里一列问句,
读者要先把每个问句翻译成主题才能定位。
| 不采用 | 采用 |
|---|
| 一段话讲完 | 概述 |
| 打什么由谁决定 | 打包内容的决定依据 |
哪些 .cppm 会被发布 | 发布的接口单元 |
| 消费者的构建会检查什么 | 消费端的构建检查 |
| 怎么消费 | 消费方式 |
| 老版本 mcpp 拿到这种包会怎样 | 旧版本 mcpp 的行为 |
| 为什么两者都不许裁剪 | 两个集合不可裁剪的原因 |
| 这些说法验证到哪一步、在哪台机器上 | 验证范围 |
| The whole idea in one paragraph | Overview |
| What decides what gets packed | What determines the package contents |
| Consuming one | Consuming a package |
| What you may rely on, and what changes | Stability guarantees |
「…的原因」「…的依据」「…的范围」是把 why 型标题转成名词短语的常用形。
保留 why 本身,去掉疑问语气。
三、词汇
不采用的类别
- 网络用语与口语:搞定、干活、坑、真香、翻车、打脸、一把梭、白给、
凉了、炸了、神器、黑科技、敲黑板、划重点。
- 拟人与比喻性行话:姊妹篇、腿(fat package 的一份产物)、travel(源码
「旅行」)、picky、happy path 的中文直译。技术术语本身可以是比喻
(rpath、sysroot),但不要新造比喻。
- 填充语:其实、说白了、简单来说、众所周知、显然、当然、值得一提的是。
如果一件事显然,就不必说;如果不显然,「显然」会让读者怀疑自己。
- 含糊的程度词:很快、非常、极其、基本上、差不多。用数字或范围替代 ——
「2.42×」「64.77s」「四个平台中的三个」。
人称
默认不使用第二人称。写动作的对象,不写「你」。
- 不采用:你可以在
mcpp.toml 里写 …
- 采用:在
mcpp.toml 中声明 …
例外:教程体文档可以使用第二人称,因为那里读者正在跟着做。教程体是
列出来的,不是推断的:00-getting-started.md、01-examples.md、
04-build-from-source.md。其余全部按参考文档处理。
引用 mcpp 自身输出的部分不受此限:did you mean 'x86_64-linux-musl'? 与
your toolchain : … 是程序打印的原文,逐字复现是要求,不是文风问题。
检查脚本因此会先剔除行内代码段再判定。
四、句式
- 陈述句优先。 命令式仅用于操作步骤(「运行
mcpp build」)。
- 一句话一个事实。 从句套从句的长句拆开。
- 不使用反问。「难道不应该……吗?」没有信息量。
- 不使用感叹号。
- 破折号克制使用:插入语用逗号或括号;破折号留给「随后是对前半句的
重述或收束」这一种用法。
五、断言的强度必须与证据相符
这是本规范里最实质的一条,也是最容易违反的一条。
| 证据 | 允许的表述 |
|---|
| 跑过、有输出 | 「实测」「测量得到」,并给出数字或报错原文 |
| 读代码推断 | 「按 X 的实现」「由 Y 决定」 |
| 未验证 | 「未验证」「尚无测试覆盖」—— 必须写出来 |
不要把推断写成实测。 反例(本仓库真实发生过):把「守卫在原生构建上失效」
写成实测结论,而它是从「targetTriple 结构上可能为空」推断的;实际运行时
它非空,结论不成立。判据:「结构上可能」不等于「运行时确实」——
要么读运行时产物,要么不要写成实测。
同理,不要用「完全」「永远」「所有平台」这类全称词,除非确实逐个验证过;
写「已在 Linux / macOS / Windows 验证」比写「全平台可用」更有价值,
因为前者可被检验。
六、双语对照
docs/X.md 与 docs/zh/X.md 是同一份文档的两个版本,不是两篇文章。
- 章节结构、标题层级、表格行数必须一一对应;
- 代码块、命令、报错原文逐字相同,不翻译;
- 术语表统一:module interface unit / 模块接口单元、implementation partition /
实现分区、import library / 导入库、install name / install name(不译)。
- 改动一侧时同时改另一侧。只改一侧会让两份文档随时间分叉,
而读者无从知道哪一份是新的。
七、结构
- 顶部一段引言说明这份文档回答什么问题,以及相关文档的链接
(用「相关文档:」,不用「姊妹篇」)。
- 表格用于枚举与对照,散文用于因果。不要用散文列举。
- 「当前边界 / Current limitations」一节是必要的,不是可选的:
没有写出边界的文档,读者只能靠踩到才知道。
八、机器检查
规则里可判定的那一半由 .github/tools/check_docs_style.sh 执行:
bash .github/tools/check_docs_style.sh
它检查三条:标题不是疑问句/口语片段;参考文档不使用第二人称;
docs/X.md 与 docs/zh/X.md 的标题结构一致(按层级序列比对,
并剔除代码块内的 # 注释 —— 第一版脚本把 ```sh 块里的 # GET, never HEAD
数成了标题,报出一个并不存在的结构分歧)。
它不检查第五节 —— 断言强度与证据是否相符需要读者判断,而那是本规范里
最重要的一条。脚本能做的事不等于规范的全部。
九、自检清单
提交文档改动前:
[ ] 标题没有疑问句、没有口语片段
[ ] 没有网络用语、没有新造比喻
[ ] 没有第二人称(教程体除外)
[ ] 每条「实测」都有数字、路径或报错原文
[ ] 没有未经验证的全称断言
[ ] 中英两版结构对应,代码块逐字一致
[ ] 有「当前边界」一节
[ ] `bash .github/tools/check_docs_style.sh` 通过
