Day01 命名的原則


Day01 命名的原則

命名的原則

  • 命名 (name) 應該要描述用途 (purpose) 而非實作 (implementation)。
  • 好的命名,應該要具備狹窄性 (narrowness) 與一致性 (consistency)
  • 俗名 (natural names) 與專有名 (synthetic names) 的選用

naming principles

用途與實作

從一個例子來談「命名」吧?你寫了一個提供排序的函式庫,裡頭有兩個函數,一個是快速排序、一個是合併排序。於是,這個函式庫,你讓它擁有兩個 API 。一個叫 quick-sort 一個叫 merge-sort

可以取更好的名字嗎?有沒有可能,你換一個方式命名,一個叫做 unstable-sort 另一個叫 stable-sort。這樣子一來,你給予的名稱描述的是函數的用途,而非實作。

狹窄性

狹窄的命名可以恰到好處地傳達它的意涵 (sense)。

過度一般性 (overly general) 的命名,會模糊化一些基本的特性,進而導致將來容易產生不相容的改動。比方說,如果排序的函數名稱 sort ,沒有區分為 stable-sortunstable-sort ,一旦有一天使用的情境需要區分這兩者時,就得要升級這個函式庫。而且昇級的方式是淘汰舊的 sort 函數,改成兩個新的 stable-sortunstable-sort 。新版的函式庫與舊版的函式庫會不相容,導致不相容的根本原因,就是一開始的命名沒有做好。

過度明確 (overly specific) 的命名,會暴露過多的實作細節,導致將來難以修改。比方說,如果你給予函數的名稱是 quick-sort ,但是,有一天又有一種新的、比快速排序法更快的排序法叫 lightning-sort 被發明了。那合理的作法,就只好再增加一個叫做 lightning-sort 的函數。然而,如果你取的函數名稱叫做 unstable-sort ,只要把實作直接更換成新的演算法即可。

一致性

程式碼的讀者並非只透過命名來了解該命名所傳達的意涵,讀者同時也透過命名周遭的程式碼 (surrounding code)、文件 (documentation)、每日的溝通對話 (everyday conversation) 來了解命名對傳達的意涵。如果要有效地傳達的話,命名、命名周遭的程式碼、文件與每日的溝通對話都要設法清楚一致地去傳達一樣的意涵,才不會讓讀者誤解。

俗名與專有名

俗名是指,命名使用一般人常用的英文。這讓它的意涵很容易被讀者直接猜到,減少了初期的認知負擔。但是,俗名的缺點是:一個俗名往往可以對應多種不同的意涵。換言之,俗名破壞了一致性。

專有名是指,命名用一些不常見的英文來加以組合。這會讓讀者無法用猜的,猜出它的意涵,必須透過閱讀文件等方式。另一方面,專有名可以確保命名與意涵的嚴格一對一對應。

在一個系統的不同層次之間,可能會有不同技術水準的讀者來閱讀。也因此,好的命名,需要適時地去選用俗名與專有名。

#name





Elements of Clojure 一書,談的不只是 Clojure ,而是 senior programmer 了解、卻不易對他人明說的隱性知識 (tacit knowledge)。

留言討論