.. Kenneth Lee 版权所有 2018-2020
:Authors: Kenneth Lee :Version: 1.0
Specification的写法问题
我们通常需要些两种设计文档，一种是构架型的，一种是Specification型的。两者没有本 质差别，仅仅是个度的差别。前者更抽象一些，比如有多少模块，每个模块的“定位”（角 色）是什么，模块之间使用什么接口，这个接口的“属性”是什么。这种设计不“specific” ，但它决定了基础的方案，这种设计我们更在乎“人情”，需要更多考虑这么一个关联关系 是否可以响应各种变化和细节的增加，它猜的成分是很重的，这个有这个的技巧，我以后 专门拉主题来讨论这个问题。
另一种是Specification型的，Specification是要严格定义一个设计的行为，常用于“接口 文档”或者“设计规范”等，比如PCIE标准，ARM SMMU Specification，JVM Specification 。
Specification要求Specific，要求精确。但精确永远都是个相对的概念。因为我们人类交 流的概念都是语言，都是名，而名来自我们双方的共同认知。是我们这个“自组织”网络，“ 自动发现，自动联结”的结果，能在一定程度上实现同步就谢天谢地了，就不指望什么“完 全一致”这种虚无的东西了。
所以，要精确，就需要先找共识。很多工程师，流，互锁，线程，虚拟机，这样的概念乱 用，最后到底在说什么，根本就搞不清楚。
所以，写Specification，第一个要求，你先去找已经被广泛认可的其他Specification来 做基础，同时，没事不要复述已经存在的概念。你基于PCIE标准来描述你的接口，你说你 的Vendor ID和Device ID是什么，说你有几个BAR空间，每个空间的定义和访问要求就可以 了，你不要来给我解释什么是FLS，不要来重新定义什么是PASID。否则PCIE标准对你提供 的帮助就消失了，因为你们两者冲突，我到底信谁？
很多写得不好的Specification，如果进行重写，基本上可以缩减到原来的一半以下，提供 的内容比原文更多，原因就在这里，你没有选要符合的要求的标准，而且抄了太多从标准 中学到的知识在里面了。
我在这个专栏里，虽然《道德经》被污染得这么厉害，我都忍不住要用，都是因为发明一 个新的名称空间的成本，这个成本不仅仅是你自己建立一个自洽空间的成本，还有别人接 受这个概念的成本，你把这个成本计算在内，你才会真正去敬畏那些已经可用的 Specification。
要信奉Specification，不要亵渎Specification。这是第一个要求，这样你才能有机会成 为别人的Specification。
第二，要用已有的概念去解释新的概念，不要随便发明新的概念。我很怕听到，“硬件发消 息给虚拟机”，“把链表连到已有的Hash上”，“如果设备工作在无状态模式，请求会在设备 上排队”……这种东西的。
老天，在硬件的角度，什么叫“虚拟机”啊？什么叫发消息给虚拟机啊？“已有的Hash”如何 定义啊？什么叫“排队”啊？什么是“无状态模式”啊？
一个硬件给软件提供接口，你只能给我的东西是：IO寄存器，内存格式要求，中断，其他 东西，你要不自己解释，要不借用其他标准。你不要另外发明一个只有你自己知道的概念 ，然后说得不亦乐乎。
我把这个叫做“工程师的小姐脾气”。小姐是不需要细节逻辑的，小姐的逻辑有丫鬟负责填 补。如果你是架构师，你可以多一点小姐脾气。如果你干的不是架构师的活，你不要把自 己当小姐，没有丫鬟来服侍你。如果你负责写Specification，你是最后一环了，细节需要 你自己填补。更不要说，很多水平不够的，不做细节定义，工作在自己才能理解的概念上 ，其实那些概念根本就不能自洽，一细化就自相矛盾。
第三，要写好Specification，定义名称空间比描述行为更重要。我推荐读者看一个简短的 Specification，RFC1950 zlib的Speicification。这里用了大于一半的篇幅来说明数据结 构表示法，Endian在这个数据结构中怎么解释，索引已知标准，然后到了格式定义，就只 剩下几句话了。
基本所有做得比较好的Specification，都不是基于功能来表述问题的，而是首先定义XX是 XX，XXX是XXX，XXX在XXX的时候应该XXXX。最后到了描述功能的时候，就一句，XXX需要以 XXX的格式提供给YYY，而YYY将以XXX的格式进行ZZZ回应。
所以，一个写得好的Specification，如果名称空间定义不能占你一半以上的篇幅，是很难 写好的。你不能说XXX进行加密的时候，如果是Stateful模式，同时密钥是128位和256位的 时候，需要这样这样，如果密钥是192为密钥的时候，大端模式的情况又将如何如何。
这样会写出一大堆的多余逻辑来。你不要认为写多余的逻辑只是你个人辛苦。其实根本不 是，写多余的逻辑不是你个人辛苦，是你个人“显得很有工作量”。因为你根本不需要分层 建立逻辑，你想到哪里是哪里，你的脑子很轻松，只是延长了你整个文档的长度。而这个 更长的文档，增加了设计的复杂度，也增加了用户使用这个Specification时的代码量，而 更多的代码量，就意味着更高的缺陷总数，是可靠性的降低。
总结起来，一个好的Specification的要求是SSL：
Specific
Shorter
Logical