API 設計— 命名之術

相信很多人都知道，寫程式的時候，多數的時間，我們都是在想變數名稱、函數名稱、類別名稱。

由於軟體正式開始使用後，不管是內部使用或是開放專案，都有外部依賴，一旦用了不好的名稱，往後修改，是相當不便，而且會破壞外部軟件的穩定度。

2010 年的 jQuery，主張了 Less is more 的概念，從 jQuery 的 API 設計，多少可以學到一些如何設計簡單易用 API 的概念。然而，不同的程式語言、編譯器都有各自適用的設計模式，不見得會通用，需要對其效能、語法限制作斟酌。 所以，Sometimes, less is more, but sometimes, less leads to confusion.

筆者雖不算相當資深，但覺得多年的設計經驗應該找個時間，統合組織一下，寫出來 (所以這篇其實藏在草稿裡很久了 ….. XD)

##資料與狀態

最常見的糟糕變數命名，很顯然的就是 a1, a2, i1, i2, j1, j2, r1, r2, 這類毫無任何含意的變數名稱（拜託，我們不是在寫 LLVM bitcode 啊，你又不是編譯器）

好吧，再進步一點，變成 product1, product2, book1, book2，好像好多了？

但事實上，有誰能從字面上分得出 product1 跟 product2 的差別？這類的變數名稱只有在一個情境下有意義，譬如：從一個 product list 中，其中符合條件第一項與第二項的 product。

其實，程式設計就是在處理資料與狀態，用來儲存資料的變數，很明顯的，因此有狀態、範圍之區分，只要掌握這個概念，基本上就不會取出令人匪夷所思的變數名稱了。

譬如，一份產品清單內，有已經上架的產品以及尚未上架的產品，其變數名稱很明顯就可命名為: $publishedProducts 或為 $unpublishedProducts，由其情境下的狀態、數量去構成。

語意是變數名稱中最重要的一部份，”published”, “unpublished” 意味著產品的狀態，所以最簡單最簡單的 pattern，就是 Adj. + N. 就可以是一個清楚的變數名稱。

單數複數表示也很重要，當我們採用複數命名，其意味著該變數很可能是一個 array 類型、collection 類型、traversable 類型的資料。

不過，如果你在同一個函數下，不需要同時處理兩種狀態的產品清單，那麼其實狀態描述多半可以省略（除非其情境有可能造成混淆才需要區分），否則多半可以寫成如下代碼:

function processProductStats() {
    $products = getPublishedProducts();
}

如上，函數名稱已經很明顯的告訴讀者，這邊取得的產品，是已經 published 的產品。

而同時處理兩種狀態的產品清單，寫成如下代碼，就很容易閱讀:

function processProductStats() {
    $publishedProducts = getPublishedProducts();
    $unpublishedProducts = getUnpublishedProducts();
}

會比下方代碼，好得多:

function processProductStats() {
    $p1 = getProducts(true, 1, 10);
    $p2 = getProducts(false, 2 , 10);
}

不蓋你，真的有人這樣寫，真心不騙。

再複雜一點，當你的資料有不同關係時，也可以加上 prep. of 作為區分，譬如:

$publishedProductsOfUser, $publishedProductsOfAdmin

如上，意味著 published product 區分為 user product 或 admin product。

如果同一個 Context 內，要標示不同的資料來源，可以用 “from”

$userFromFacebook, $userFromTwitter

當然，也可以直接簡化為 $twitterUser 或 $facebookUser，”from” 只是最為一個當你不知道如何命名時，最安全的一個手法。

而匈牙利命名法也不是全然的有病，在某些場合下，其實相當有用，譬如現代框架常用的 ORM 會提供 Collection 這類的物件，而 Collection 可以轉成Model 的陣列資料，如下:

$products = new ProductCollection;
$items = $products->items(); // 實際上是 Product[] 而非 array of array

如上場合使用 $items 其實沒有什麼大問題，但多數時候，我們會處理多個 Collection:

$products = new ProductCollection;
$categories = new CategoryCollection;

全部轉成 array of model record 呢?

$products = new ProductCollection;
$categories = new CategoryCollection;
$productItems = $products->items();
$categoryItems = $categories->items();

好，目前都沒有什麼大問題，不過我們現在遇到一個狀況，就是需要將資料組合後，以 JSON 格式送出，而 encode_json 只吃 array 型別的資料，所以我們需要將 Array of model record 轉成 array of array，怎麼辦？程式碼很可能變成這樣:

$products = new ProductCollection;
$categories = new CategoryCollection;

$productItems = [];
foreach ($products as $product) {
    $productItem = $product->toArray();
    $productItem['types'] = $product->types->toArray();
    $productItems[] = $productItem;
}
$output = [
    'products' => $productItems,
    ......
];

上面這段程式碼，看起來沒有什麼大問題，不過他違反了一個規則 — Consistency 一致性

上上段程式碼，我們使用 suffix -items 作為 array of model records 表示，但這邊，我們卻使用 suffix -item 以及 suffix -items 作為 array of array 的表示，如果先看第一段代碼，再看這段代碼，就會知道容易造成混淆的地方為何了。

整理一下，加上型別名稱，是否比較清楚?

$products = new ProductCollection;
$categories = new CategoryCollection;

$arrayProducts = [];
foreach ($products as $product) {
    $arrayProduct = $product->toArray();
    $arrayProduct['types'] = $product->types->toArray();
    $arrayProducts[] = $arrayProduct;
}
$output = [
    'products' => $arrayProducts,
    ......
];

這邊，取名為 $arrayProduct 以及 $arrayProducts 的主要原因，是為了強調其型別為 array，因此作為 prefix 放在 N 的前面，同樣的 $productArray 或是 $productsArray 也是可行，或甚至更清楚的名稱也是可行，如 $arrayOfProductArray 以及 $productArray… 等，同樣都達到了型別標示的目的。 ##常見縮寫

而常見變數名稱如 $i 其實是 $index 的縮寫，所以也不用大驚小怪，而 $j 則是常見用來作為第二層迴圈的索引值，這幾個用法，都是相當通用，所以也不用避諱。

$a, $b ??

隨著 functional 寫法越來越普遍，多數陣列處理也會用上 comparator，譬如 sort(), 其中 $a , $b 多半用來表示兩邊不同的變數，這個也蠻常用的，算是很簡潔的寫法，畢竟 comparator 函數內容通常很精簡，不太需要過度清楚的區分不同變數。

##操作資料

目前為止以上概念都很簡單，我們現在懂了變數命名，更進一步的，就是撰寫操作這些資料的代碼，而操作這些資料，我們需要函數，因此函數名稱是比變數名稱更重要的，因為它不僅僅是操作資料，也是對外公開表示：「Hey I can do this」

如果你取錯名稱，在下一個版本把它改了名字，套件升級的使用者只會覺得憤怒，因為你讓他們的軟體增加了不穩定性… XD

你能想像當你走進一家政府機構辦事，該路上的指示牌到告訴你 XXX 事務請往右走到底，第一次很順利，隔年你又去辦事，跟著指示牌走到底，結果居然換位置了？當然很怒啊。 所以這個指示牌有沒有更新，就很重要，在軟體裡面我們可以把它叫做 Changelog 或 Migration，通常會以 CHANGELOG 或用 MIGRATION, UPGRADE 命名…之所以全部用大寫，是因為小寫的話沒人看，最後作者怒了，全部都用大寫，其意義就是「拜託你給我看這個文件」

當然，Migration, Upgrade 越少越好，雖然我們沒辦法一次就看到好的設計，但我們至少可以在一開始的時候，把初步的設計做好。 函數命名

在講函數命名之前，我想可以先來簡單介紹一下，幾個通用性的動詞，基本上理解這幾種動詞背後所隱含的意味，函數命名就不會錯太多。

以下幾個 prefix- 不是絕對的限制，只是一個通用、常用的準則，用以參考：

get-

通常類別方法以 get- 開頭，意味著我們要取得某項屬性或數值，很顯然的，我們沒辦法透過屬性直接存取，所以才需要 get- ，而 get- 最重要的一點，就是他「只做簡單回傳，不作修改」，也因此，一個 get method 不應該修改物件的狀態、修改物件內容、也不該調用複雜資料庫查詢

除非整個類別是專為遠端 API 設計，其 get- 才比較 make sense，不過也須注意，類別本身屬性的取得和遠端資料取得都使用 get- ，很可能會造成混淆。譬如:

$client = new MyAppAPI;
$client->getHost();    // 好像沒有 API query?
$client->getUserId();  // 到底有沒有 API query 呢?
$client->getStories(); // 到底有沒有 API query 呀!!???!

如上範例，使用 fetch- prefix 改為如下代碼，可能清楚很多:

$client = new MyAppAPI;
$client->getHost();
$client->fetchUserId();
$client->fetchStories();

get- prefix 意味著，輕巧的、快速的拿到某個資料… 以此類推，set- 也是一樣。

不過，如果是單純的函數，而非類別方法，則 get- 就無此限制，命名方式較為彈性。

set-

通常被用在設定屬性，與 get- 一樣，不該用在資料庫操作。我們在另外一篇文章「建構子設計之道」有討論 set- 正確的使用時機。

query-

上面說的 get- 不該調用遠端 API 或資料庫操作，讀者肯定心中充滿了疑問，「什麼？不用 get? 我看你才不懂吧」

事實上，還有一個 prefix 很好用，就是 query-，query 意味著查詢，而且是帶有條件的，所以使用者可能會期望 query- method 有條件參數可以傳遞。查詢有很多種含義，不管是 database query, api query 都算是 query，當開發者查看 API 規格，甚至只看得到 caller 怎麼呼叫，”query-” 很明顯的就可以讓開發者瞭解 — 喔，這個可能得花一點時間，而且可能會有一些 ”溝通” 要做

do-

do- 列在這邊，實際是常見的錯用 prefix- ，很多時候會看到有人寫 doUpdate, doQuery, doKill 這類包含 do- prefix 的函數名稱，但其實 do- 很沒意義。 如果你只是為了區分 doUpdate 以及 update 這兩個函數名稱，不如就用底線開頭來隱藏另外一個實作吧 _update, update 表面上看起來，很明顯的 update 才是真正的開放 API，而 _update 的 scope 建議應該為 private 或 protected。

fetch-/store-

fetch- 與 store- 通常是對應的，比 query 更模糊一點的是，fetch- 通常不帶有複雜條件，譬如 fetchProduct, fetchBooks, fetchUserStories 等等，對象通常是資料庫，當然場景需求不同，沒有一定要如此限制。

而當 “fetch”, “store” 同時出現在同一個類別，就可能需要考慮到一致性，因為使用者可能預期 “fetch”, “store” 是對同一個 storage 操作，不該 fetch from A, 但 store to B.

build-

通常用在 — 給予某些參數，建置某個結構或物件。 筆者常用的是 — 給予某些簡單的參數，建置某一用途的 Config 物件或 Map，譬如 buildReactProducctAppConfig。 build- 也可能意味著，建置資料庫內某種用途的資料，譬如 buildBaseData、buildUserData，但其意義與包含此函數的類別名稱有關。

create-

通常被用在 ORM Record 建置，如 ActiveRecord Pattern 常使用這個 create() method 來建置新的 Record。 create- 與 build- 很像，但就筆者看來，這兩者不同的地方在於，create- 有明顯目標跟範圍，譬如 Product::create().. Book::create(), createOrder() … 等等，而 build- 如 buildBaseData 等，不是這麼明確。（但也有可能有筆者沒有想到的案例，若有的話，之後補上 XD）

new-

new- 其實與 create- 不同，new- 很明顯的只意味著建構一個類別的實體化，取名以 new- 開頭，那麼隱含的操作應該不包含資料庫操作。

remove-, delete-

remove- 與 delete- 其實差異也不是太明顯，但就筆者來看，remove- 意味著從某個資料集，移除掉這個項目，這個 “移除” 很可能只是移除關聯性，並不會刪除實體資料，而 delete- ，很明確的意味著是實體資料的刪除。

traverse-

在處理樹狀資料時，traverse- 很好用，traverse- 意味著會遍歷一整個樹，常用在處理 AST 的部分。

下集待續

(也不知道有沒有下集….先寫到這邊，不然等到寫完也不知道什麼時候了。)