用蠶繭表示法寫簡潔實用的介面文件

2021-07-10 17:43:42 字數 624 閱讀 8027

蠶繭表示法是乙個介面描述的規範。我用它的乙個典型的場景就是寫內部介面文件。蠶繭法體現了兩個思想:

使用簡潔的語法來描述物件、陣列、字典等複雜結構。

通過命名規範,讓乙個名字自發地體現出它的型別。如名詞複數用於物件陣列,以id結尾預設是整型等等。

根據id獲取訂單:

getorder(id) ->

address:

lines:

其中,返回物件使用了蠶繭法進行簡要的描述,將複雜資料型別層層剝開直到基本型別,而基於命名約定,引數或屬性的名稱隱含了它的基本型別,無需再多解釋。在內部團隊,如果每個人(架構師,開發,測試人員)已經對產品中的基本術語如order-訂單,item-使用者購買的物品這些了解之後,上面的設計幾乎不需要任何多餘的描述文字,因為它已經清楚的展現了每個物件的資料型別和含義:

可以以這樣簡潔的描述讓所有參與的人都能看的很明白,主要得益於大量的約定,比如利用蠶繭法描述物件,陣列,字典等,再如良好的命名規範,不僅從名稱中可以了解它的含義,也暗示出它的型別。

乙個產品的內部介面會有很多,少則十幾二十個,多則有上百個。怎樣才能維護好它們?要不要有文件?應該怎樣寫文件?

筆者對內部文件的觀點是:

演算法表示法之大O表示法

我們在描述演算法複雜度時,常用o 1 o n o logn o n logn 等表示對應演算法的時間複雜度,是演算法的時空複雜度的表示。不僅僅用於表示時間複雜度,也用於表示空間複雜度。這種表示法稱之為大o表示法 大o表示法是演算法的一種特殊的表示法,指出了演算法的速度有多快,它指出了演算法執行時間的...

匈牙利表示法

使用3個字元做字首來表示資料型別和控制項型別,稱之為匈牙利表示法。之所以這樣稱呼,部分原因是因為它的發明人charles simonyi是匈牙利人,還有部分原因是這些字首使變數名稱看起來像外語。如 dim strname as string 使用 用於變數 私有成員引數和常數 有選擇性的 而不應該把...

匈牙利表示法

匈牙利表示法 它通過在每乙個表示符名字的前面放置乙個資料型別助記符,為程式設計師提供了對識別符號的即時識別。1 mfc 控制代碼 控制項及結構的命名規則。windows型別 樣本變數 mfc類 樣本物件 hwnd hwnd cwnd pwnd hdlg hdlg cdialog pdlg hdc h...