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