相信很多人都知道,寫程式的時候,多數的時間,我們都是在想變數名稱、函數名稱、類別名稱。
由於軟體正式開始使用後,不管是內部使用或是開放專案,都有外部依賴,一旦用了不好的名稱,往後修改,是相當不便,而且會破壞外部軟件的穩定度。
2010 年的 jQuery,主張了 Less is more 的概念,從 jQuery 的 API 設計,多少可以學到一些如何設計簡單易用 API 的概念。然而,不同的程式語言、編譯器都有各自適用的設計模式,不見得會通用,需要對其效能、語法限制作斟酌。 所以,Sometimes, less is more, but sometimes, less leads to confusion.
資料與狀態
最常見的糟糕變數命名,很顯然的就是 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-
通常用在 — 給予某些參數,建置某個結構、複雜的參數或物件。 筆者常用的是 — 給予某些簡單的參數,建置複雜的 Parameters 或 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 的部分。
下集待續
(也不知道有沒有下集….先寫到這邊,不然等到寫完也不知道什麼時候了。)