keep-the-caveat-with-the-number

你正准备把一个测量出来的数字放到读者会看到的地方：README、落地页、发布说明、仪表盘、报告。这个数字是真的，但它需要旁边有一句话才不会误导人——样本量很小、切片选得容易、效应并不显著、基准测试是我们自己做的。

这条不适用于那种含义本身就完整的数字。"构建耗时 41 秒"不需要任何附加说明。

1. 先写附加说明（caveat），再写数字。如果你没法用一句话说清这个限制，就说明你对这次测量的理解还不够深，还不该发布它。
2. 让附加说明在结构上绑定在一起。放进同一个组件、同一个表格行、同一个函数返回值里——做成没有它就渲染不出数字的样子。
3. 把它放在数字的上方，或者旁边。不要放在下方。
4. 让数字本身是派生出来的：从测量产生的那个产物里读取它，这样测量结果变了，数字也会跟着变。

过度使用这条会让普通的报告变得沉重：不是每一个数字都是基准测试结果，给一个不需要附加说明的数字硬加一句，会训练人们养成跳过附加说明的习惯。

更难的风险在于，一套机制会让人感觉它就是全部答案。一个总是会渲染出某句附加说明的组件，并不会检查这句话是不是正确的那一句。这句话依然必须由人诚实地写出来；这套机制只是防止它日后被删掉。