跳到正文

数字、单位和时间

一致地表示量值、范围、日期、时区、精度和配置中的单位。

把数值和单位写完整

数量、版本、工程测量值使用半角阿拉伯数字。正文中数值和单位之间留一个半角空格,例如 250 ms、8 MiB、25 °C 和 3 个文件。本指南把百分号和角度符号紧贴数字,例如 25% 和 90°。单位符号保留大小写,说明存储大小时明确十进制或二进制单位。

含义推荐写法需要确认的信息
耗时250 ms测量的是请求、构建还是索引加载
存储量64 MiBMiB 是二进制单位,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
}

同一示例中,显示给读者的时间和接口值应表示同一时刻。需要换算时,在对应的配置参考中标明单位和默认值。