[C#] API 設計規則

API 設計規則

先前看了一篇文章，在講述 API 的設計理念，方法與規則，分為三個階段。算是一篇不錯的文章，很實用的，於是就做了點筆記，把重要的內容記錄下來，提醒自己將來好遵守。

基礎 : 考慮用詞與語法一致

  • API 的命名拼寫要正確。
  • 準確的用詞。(正反義詞不可混用。)
  • 注意單複數。
  • 不要誤用詞性。 (例如 : Success/Failure<名詞>，Succeed/Fail<動詞>，Successful/Failed<形容詞>)
  • 處理縮寫。(Pascal 與 Camel 命名方式)
  • 用對時態和語句。(盡量避免使用被動語句)

進階 : 多思考語義與可用性

  • 單一職責原理。(SRP，一個類別或是方法，只專職做一件事就好)
  • 避免副作用。(Expected 與 OCP，當類別擴充時，不會影響到原生的系統結構，要與預期的結果相符。)
  • 合理的設計函數參數。(相關性越高的參數，越要將參數前置，或是將同類型的參數整合到所傳遞的物件中。)
  • 合理的運用函數多載。(Overload。Hint : 當傳入的參數，無法進行有效區分時，建議不要選擇多載)
  • 一致性的術語表
  • 遵循一致性的 API 風格

Note : 一致性可以最大化程度的降低訊息熵

一致性範例
--------------------------------------
pic   | 圖片    | image, picture
--------------------------------------
path  | 路徑    | URL，url, uri
--------------------------------------
on    | 事件綁定| bind, addEventListener
--------------------------------------
off   | 解除綁定| unbind, removeEventListener
-------------------------------------------
emit  | 觸發事件| fire, trigger
--------------------------------------
module| 模組    | mode
--------------------------------------

Note :　函數簽名(Function Signature)，滿足函數簽名的三要素，1. 函數名　2. 參數設定 3. 返回值類型

深入 : 要考慮整個系統與整個系統架構與布局。

  • 版本控制 (Git, CVS, and SVN，大版本號不變的情跨下，API 保證向下相容)
  • 確保向下相容 (不要輕易地刪除公開 API，可以使用 #Deprecated)
  • 設計擴展機制 (OCP，對擴展開放，對修改封閉。接口足夠抽象。)
  • 控制 API 的抽象級別。(1. 高抽象。2. 場景範圍。) 1. Abstract 2. When 3. Where 4. Concrete
  • 收斂 API 集 (1.對API進行減法 2. 收斂近似職責的 API 3. 多型)
  • 發散 API 集 (擴充不同的功能)
  • 訂定 API 可支援的策略。 (1. 大版本號的支持週期多久 => V.v.x.... 2. Long Term Support 3. 如何從舊版升級成新版本)
1. 邏輯和抽象
2. 領域知識 (Domain Knowledge)
3. 語感 (讓人容易閱讀)

參考

  1. 來源-API設計之道

留言

張貼留言

這個網誌中的熱門文章

[Tools] GCOV & LCOV 初探

[Tools] gcov & lcov gcov 是一套代碼覆蓋率的工具，可以有效地查閱分析程式，找出程式中重載的部分，它也是 gcc 中的內建工具。 lcov 則是可以將 gcov 所分析完的結果，轉譯成 html 。 Required Packages $ apt update $ apt upgrade -y $ apt install gcov lcov gcov $ gcov -h Usage: gcov [OPTION]... SOURCE|OBJ... Print code coverage information. -h, --help Print this help, then exit -v, --version Print version number, then exit -a, --all-blocks Show information for every basic block -b, --branch-probabilities Include branch probabilities in output -c, --branch-counts Given counts of branches taken rather than percentages -n, --no-output Do not create an output file -l, --long-file-names Use long output file names for included source files -f, --function-summaries Output summaries for each function -o, --object-directory DIR|FILE Search for object files in...
閱讀完整內容

Quilt Patch 管理操作方法

QUILT in Linux 管理 Patch 的工具 Edit quiltrc file Ubuntu 預設使用 nano cat > ~/.quiltrc <<EOF QUILT_DIFF_ARGS="--no-timestamps--no-index -pab --color=auto“ QUILT_REFRESH_ARGS="--no-timestamps--no-index -pab" QUILT_PATCH_OPTS="--unified" QUILT_DIFF_OPTS="-p" QUILT_SERIES_ARGS="--color=auto" EDITOR="vim" EOF EDITOR="nano" 修改預設的編輯器 在 Ubuntu 14.04 環境下，即使已經新增 .quiltrc 檔案了，但是編輯時，預設還是使用了 nano。 為了要使用熟悉的 vim ，只要在 .bashrc 下，直接 export EDITOR=vim ，就可以解決這個問題了。 --- .basrc --- export EDITOR=vim -------------- Package 先去建立 Package make package/xxx/{clean|prepare|compile} V=s Quilt 進入編譯目錄 cd build_dir/target*/xxx 查詢 Patch 查詢所有 Patch 綠色的字 : 已經 apply 的 patch 橘色的字 : 已經 apply 的 patch, 且是目前最新的 patch 白色的字 : 還沒 apply 的 patch quilt series 查詢 apply Patch quilt applied 查詢未 apply Patch quilt unapplied 查詢下一個 patch quilt next 查詢最新的 patch quilt top 查詢 patch 包含那些檔案 quilt files Push/Pop Patch p...
閱讀完整內容

[C#]C# Coding 規則

C# Coding 規則 標示符命名規則 標示符是指變數，類別或是結構，和類別與結構的成員的變數名稱。 必須以字母或底線開頭。 不能將關鍵字作為標示符用，如果需要，則須在標示符號前，加上前綴字符 @ 。 標示符也可以包含 Unicode。 命名規則 一般對於變數或是類別方法名稱的宣告，或將該宣告的變數，以有意圖的方式來命名。(單字組合) 一般命名的規則可分為兩類，一個是 Pascal ，另外一個則是 Camel。 Pascal : 大小寫形式，每個單字開頭皆為大寫，一般 Pascal 大都使用在 非參數 的宣告，即類別名稱、方法，屬性等。 例如 : class Person。 ToDoSomething()。 public int Age {get;set;}。 Camel : 開頭的單字為小寫，而後整個單字組開頭皆為大寫，一般用在傳遞參數或是宣告變數上使用。有時候，有些人的宣告的變數前面會加上底線。 一般都是私有成員使用 Camel 傳遞給方法的所有名稱都應該是以 Camel 形式 透過 Camel 也可以使用大小寫來區分兩個不同的對象。 例如: private string name; private string firstName; private string lastName; private string _name; ... class Person { private int _name; public Person(string name) { this._name = name; } } ... private int _age; public int Age { get {return _age;} set { _age = value;} } 命名風格 命名的風格名稱最好要一致。例如 : ShowConfig()，EditConfig()。 命名空間的名稱 MS 有建議命名空間的法則，即 . 。 命名名稱和關鍵字 兩者不應該互相衝突。
閱讀完整內容