Framework Design Guidelines 筆記 (4): 低門檻原則

關鍵詞彙
  • Framework(框架;類別庫)
  • The principle of low barrier to entry(低門檻原則)
低門檻原則指的是:
框架必須提供一個較低的入門門檻,讓初學者可以透過簡單的小實驗來學習這套框架。 (p.21)
然而,一套類別庫要做到功能強大、完整,同時又要易學易用,卻不是那麼容易。像 .NET Framework 這類比較大型的類別庫,裡面的類別非常多,為了方便學習、查找,就一定得要有適當、合理的分類和命名,否則可能寫了好多好用的工具,卻藏在類別庫中某個很深層的角落沒人發現。這分類的關鍵,主要就在 namespace 的運用。

因此,若要設計出容易學習的 API,應做到下列幾點(p.22-23):
  • 平常寫程式經常用到的類別要能很容易找到,而且成員的數量要適中。比如說,一個 namespace 裡面包含 500 個型別,結果其中只有少數幾個是真正關鍵或常用的。這種齊頭式平等的分類方式不僅不易學習,在撰寫程式的時候也多少會帶來困擾(IntelliSense 一次列出一拖拉庫的成員清單)。
  • 要讓開發人員隨手捻來就能立即使用。如果使用某個類別之前,還得先建立其他類別的 instances、設定一堆必要的屬性、以及寫很多初始化的程式碼,那麼,初學者為了寫一點實驗用的小程式就得大費周章,可能試個幾次就打退堂鼓了。
  • 要很容易找到錯誤的原因,以便迅速解決問題。例如,API 應該儘量考慮可能發生的 exceptions,並且在例外發生時丟出清楚的錯誤訊息,讓程式設計師能夠從訊息來判斷哪裡出了問題。
關於最後一點,我個人的感受特別深,因為印象中我總是經常重複這樣的牢騷建議。十年前碰到隱藏錯誤或訊息曖昧不明的情況,十年後似乎也沒有太大的改變,還是得不斷拜託寫底層元件的人不要再丟出「發生錯誤了!」這種只有神才知道原因的訊息。(更別提 catch 區塊裡面什麼都沒有的寫法)

據我瞭解,支持「精簡錯誤訊息」的一個主要考量是:end users 根本看不懂那些底層的詳細錯誤訊息;顯示太詳細反而造成使用者的困擾。

我想問題的關鍵在於:錯誤訊息是有分類型或等級的。一般使用者的操作錯誤,應用程式自然很容易顯示最精簡、易懂的訊息(例如:請先選擇這個,再按那個),那是比較偏向 warning、information 之類的告知訊息。而寫底層 API 的設計師要處理的卻是比較特殊的「例外狀況」,這些例外狀況所引發的錯誤訊息雖然對 end users 來說沒太大用處,但卻是維護人員接到電話或 e-mail 時一個非常重要的線索。把這個線索隱藏起來,就像鴕鳥把頭埋進沙堆一樣,對解決問題真的一點幫助也沒有。

詳細描述錯誤訊息只是設計 API 的最基本要求而已,Chris Sells 認為,好的錯誤訊息除了描述 what,還要提示如何解決:
In my own programming, I dearly love error messages that say what I did wrong and how to fix it. All too often, all I get is the former, when all I really care about is the latter. (p.23)

相關文章

沒有留言:

技術提供:Blogger.
回頂端⬆️