简单英语（Simple English）
用尽可能少的普通词汇说重点，然后停下。细节让读者打开代码去看。
力求简洁
- 直奔主题：说明事物做什么，如果原因不明显也要一并说清。
- 省略代码或差异已经展示的内容：涉及的文件、步骤的顺序、代码处理的边界情况。
- 使用行业的紧凑短语：“drop unused icons”，而不是“drop the icons that nothing uses”。
- 每件事只说一次。
- 删减词汇，而非事实。保留读者理解问题所需的每一步，并说明后果：“that date can differ from the day CI makes the release”，而不是“the heading is written before the release day”。
保持清晰
简洁不等于晦涩。
- 每个句子表达一个想法，包含主语和动词。不要使用分号、谜语或口号（例如“no release, no type”）。
- 把主语放在句首，并指明动作的执行者：“C++ computes X”，而不是“X is computed in C++”。
- 使用简单时态，对于仍然成立的事实使用现在时：“QML never re-evaluates bindings on it”，而不是“never re-evaluated”。
- 条件句写成
If X, Y.的形式。 - 当名词相隔一个从句，或者可能有多个名词符合条件时，重复该名词，而不是使用“it”“they”或“those”。
- 保持“which”和“whose”从句简短。如果从句本身有很长的主语，就另起一句：“Debian and Ubuntu Qt packages don't have it”，而不是“, which Debian's and Ubuntu's Qt packages leave out”。
- 直接表达否定：“ignore values outside the range”，而不是“take no value past the range”。不要通过宾语来否定：“the edit didn't emit updated()”，而不是“the edit emitted no updated()”。只在“neither”之后使用“nor”。
听起来地道
文本读起来必须像英语为母语的开发者所写。如果某个短语读起来像翻译，就重写，即使重写后多一个词。
- 使用复合名词，而不是一串“of”：“app settings”“the CSV file dialog”“Debian and Ubuntu Qt packages”。只有在无法使用复合名词时才使用所有格，例如“the sheet's density”，并且绝不要连续使用两个所有格。每个短语最多允许一个“of”。
- 使用行业惯用动词：“show”“report”“fix”“support”“handle”“check”。不要让代码像人一样“告诉”“回答”或“携带”。在C++意义上，“own”仅用于所有权。
- 每个概念使用一个词：选择“check”或“verify”、“settings”或“options”，并保持一致。
- 在列表中不要重复冠词：“the frame and delete button”。
- 用“must”表示要求，用“can”表示可能性。避免使用“should”“may”和“might”。
- 使用“for example”，而不是“e.g.”。使用美式拼写。
- 删除以下词汇：“leverage”和“utilize”（用“use”）、“in order to”（用“to”）、“prior to”（用“before”）、“ensure”“simply”“just”“easily”“seamlessly”“robust”“powerful”“comprehensive”“functionality”“it is worth noting that”“with this change”“is designed to”“allows you to”（直接说出事物和它的动词）、“under the hood”“out of the box”。
改造前后对比，来自真实提交标题：
| 改造前 | 改造后 |
|---|---|
| keep the settings of the app out of documents | don't save app settings in documents |
| Graph: tell the reader when an export fails | Graph: report export errors |
| add CardButton, the icon button of the top row of an object | add CardButton, the icon button on an object's top row |
| Sampler: take no value of a discrete object past its range | Sampler: ignore discrete object values outside the range |
| stop a full release whose notes carry another day | check the date in the release notes before a full release |
| build on Ubuntu 26.04, with its packages of Qt | build on Ubuntu 26.04, with its Qt packages |
按文本类型
提交信息
- 主题写成简短的祈使句，脱离差异也能理解：“limit document values to the settings panel bounds”，而不是“keep the numbers of a document within the range of the panel”。
- 一个提交只做一件事。如果正文需要第二个主题，则将提交拆分。
- 正文以代码现在做什么开头，然后简要说明为什么。
- 用“also”标记主题之外的事实：“Both reads also skip unknown keys, because newer versions can add some.”
- 省略读者已知的背景信息。不要复述差异或为变更辩护。
代码注释
- 默认不写注释。仅在代码未显示的原因、隐藏的不变量或变通方案处编写。
- 说明代码做什么、由此产生什么以及为什么，每个用一句简短的话。跳过代码已经展示的部分。
- 指明API名称，不使用隐喻。祈使句没问题：“skip identical writes: they still update the mtime”。
- 写出你会对同事说的“为什么这里这么做？”的答案。指明具体效果，例如“xmin stays on the left”，而不是总结性的“the bounds sit where they are”。
示例：
- 改造前：
// a vertical list keeps its width a secret, so the style paints a stray handle - 改造后：
// a vertical ListView leaves contentWidth at -1, which the style renders as a collapsed handle - 改造前：
# the runner's glib and libsystemd need its new glibc, so the AppImage uses the host's glib and libdbus. linuxdeploy still copies the libraries that only they need, so the list names those too - 改造后：
# don't bundle glib, libdbus and their dependencies. The AppImage then loads the host's versions. The Ubuntu 26.04 versions need glibc 2.43, which older distros lack.
文档
- 描述代码现在的行为。指明事物及其用途，并指向包含详细信息的文件。
- 三个或以上的并行项目使用无序列表。
- 样式、模块和标识符名称放在反引号内：
FluentWinUI3。 - 对于可能变化的第三方软件的事实，用“currently”或版本号标记：“Debian and Ubuntu Qt packages currently don't have it.”
错误消息： 发生了什么，原因（如果已知）以及该怎么做。不要道歉。
工具提示： 该控件设置什么。
代理指令： 每个句子一条规则，条件在前。
保持原样
代码、标识符、命令、路径、引用的消息、产品名称以及按钮、标签页、字段和菜单项的名称。
交付前
以读者的身份通读文本一遍。删掉对读者没有帮助的每个句子。检查留存的每个句子是否第一眼就能读通，听起来像平常的英语。
如果你在聊天中解释过同一件事，请比较两者。如果聊天版本更清晰，就使用它。