把数值和单位写完整
数量、版本、工程测量值使用半角阿拉伯数字。正文中数值和单位之间留一个半角空格,例如 250 ms、8 MiB、25 °C 和 3 个文件。本指南把百分号和角度符号紧贴数字,例如 25% 和 90°。单位符号保留大小写,说明存储大小时明确十进制或二进制单位。
| 含义 | 推荐写法 | 需要确认的信息 |
|---|---|---|
| 耗时 | 250 ms | 测量的是请求、构建还是索引加载 |
| 存储量 | 64 MiB | MiB 是二进制单位,MB 是十进制单位,两者量值不同 |
| 比例 | 命中率为 25% | 分母是什么,在哪段时间统计 |
| 配置值 | 将 timeoutMs 设为 250 | 字段要求的单位为毫秒 |
量值采用能支持判断的精度。结果来自测量时,交代输入规模、测量环境和统计方式。由格式或上游要求保留小数位时,按该格式记录。
明确范围的边界
对区间写出单位和边界是否包含。例如,“超时时间至少 100 ms,至多 500 ms,两端都可以取到”。版本范围给出可辨认的版本号,例如“支持 2.1 和 2.2”。“最新”“旧版”“最近”与操作有关时,补充准确范围或日期。
区分人读日期和机器格式
正文写“2026 年 11 月 20 日”。需要确定具体时刻时,写明时区,例如“2026 年 11 月 20 日 09:30(UTC+08:00)”。示例中的 ISO 字符串和时间戳沿用接口格式,并说明秒、毫秒或时区偏移。
{
"generatedAt": "2026-11-20T09:30:00+08:00",
"buildDurationMs": 250
}
同一示例中,显示给读者的时间和接口值应表示同一时刻。需要换算时,在对应的配置参考中标明单位和默认值。