【摘抄】
Six Characteristics of Good APIs
An API is to the programmer
what a GUI is to the end-user. The 'P' in API stands for "Programmer",
not "Program", to highlight the fact that APIs are used by programmers,
who are humans.
We believe APIs should be minimal and complete,
have clear and simple semantics, be intuitive, be easy to memorize, and
lead to readable code.
* Be minimal: A minimal API is one
that has as few public members per class and as few classes as possible.
This makes it easier to understand, remember, debug, and change the
API.
* Be complete: A complete API means the expected
functionality should be there. This can conflict with keeping it
minimal. Also, if a member function is in the wrong class, many
potential users of the function won't find it.
* Have clear and
simple semantics: As with other design work, you should apply the
principle of least surprise. Make common tasks easy. Rare tasks should
be possible but not the focus. Solve the specific problem; don't make
the solution overly general when this is not needed. (For example,
QMimeSourceFactory in Qt 3 could have been called QImageLoader and have a
different API.)
* Be intuitive: As with anything else on a
computer, an API should be intuitive. Different experience and
background leads to different perceptions on what is intuitive and what
isn't. An API is intuitive if a semi-experienced user gets away without
reading the documentation, and if a programmer who doesn't know the API
can understand code written using it.
* Be easy to memorize: To
make the API easy to remember, choose a consistent and precise naming
convention. Use recognizable patterns and concepts, and avoid
abbreviations.
* Lead to readable code: Code is written once, but
read (and debugged and changed) many times. Readable code may sometimes
take longer to write, but saves time throughout the product's life
cycle.
Finally, keep in mind that different kinds of users will
use different parts of the API. While simply using an instance of a Qt
class should be intuitive, it's reasonable to expect the user to read
the documentation before attempting to subclass it.
好的API的六個特性
API是面向程序員的，用來描述提供給最終用戶的GUI是什么樣子。API中的P帶表程序員（Programmer），而不是程序（Program），用來強調(diào)API是給程序員用的，給人類的程序員用的。
我們堅信API應該是最小化且完整的，擁有清晰且簡單的語義，直覺化，容易記憶，并且引導人寫出易讀的代碼。
* 最小化：最小化的API是指一個類盡可能只擁有最少的公開成員且盡可能只擁有最少的類。這個原則可以讓API更簡單易懂，更好記，更容易除錯，且更容易改變。
* 完整的：完整的API是指要提供所有期望的功能。這個可能與最小化原則相沖突。另外，如果一個成員函數(shù)屬于一個不應該屬于的類，很多潛在的使用者都會找不到這個函數(shù)。
* 擁有清晰且簡單的語義：就像其他設計工作一樣，你必須遵守最小驚奇原則（the principle of least
surprise）。讓常見的任務簡單易行。不常見的工作可行，但不會讓用戶過分關(guān)注。解決特殊問題時，不要讓解決方案沒有必要的過度通用。（比
如，Qt3中的QMimeSourceFactory可以通過調(diào)用QImageLoader來實現(xiàn)不同的API。）
*
直覺化：就像電腦上的其他東西一樣，API必須是直覺化的。不同的經(jīng)驗和背景會導致在判斷什么是直覺而什么不是時不同的感覺。如果一個中級用戶不讀文檔就
可以使用（a semi-experienced user gets away without reading the
documentation，沒懂這里的get away該怎么翻譯），并且一個程序員不懂API就可以理解縮寫的代碼，這種API就是直覺化的。
* 易于記憶：讓API易于記憶，使用統(tǒng)一且精確的命名方法。使用可識別的模式和概念，并且避免縮寫。
* 引導易讀的代碼（Lead to readable code）：代碼一經(jīng)寫就，會讀（并且除錯和修改）多次。易讀的代碼可能會花點時間來寫，但是可以節(jié)省產(chǎn)品周期中的其他時間。
最后，記住，不同類型的用戶會用到API的不同部分。雖然簡單的實例化一個Qt類是非常直覺化的，讓資深專家在試圖子類化之前讀一遍文檔，是很合理的。
來自：
http://doc./qq/qq13-apis.html
http://googollee.blog.163.com/blog/static/1159411200811321030894/
關(guān)于原文中的便利陷阱和布爾參數(shù)陷阱值得說明：
便利陷阱來源于想一次性完成一系列操作的思想，出現(xiàn)的問題是：不利于調(diào)用者理解參數(shù)實際的意義，不符合最小化操作。建議：一個函數(shù)一個操作，提供標準的調(diào)用實例。
比如：
QSlider *slider = new QSlider(12, 18, 3, 13, Qt::Vertical,
0, "volume");
遠比下面那樣難讀（甚至難寫）：
QSlider *slider = new QSlider(Qt::Vertical);
slider->setRange(12, 18);
slider->setPageStep(3);
slider->setValue(13);
slider->setObjectName("volume");
從這里可以看出下面一種更容易閱讀和使用~
布爾參數(shù)陷阱來源于這樣的思考：想讓調(diào)用者自己設定對應的布爾值，出現(xiàn)的問題是：調(diào)用者不能馬上知道其布爾值的真實意義。建議用命名方式來解決，如下：
傳統(tǒng)的例子是repaint()，這個函數(shù)帶有一個布爾參數(shù)，來標識是否擦除背景（默認擦除）。這讓代碼通常寫成：
widget->repaint(false);
初學者很容易把這句話理解成“別重畫”！
這樣做是考慮到布爾參數(shù)可以減少一個函數(shù)，避免代碼膨脹。事實上，這反而增加了代碼量。有多少Q(mào)t用戶真的記住了下面三行程序都是做什么的？
widget->repaint();
widget->repaint(true);
widget->repaint(false);
一個好一些的API可能看起來是這樣：
widget->repaint();
widget->repaintWithoutErasing();
針對布爾參數(shù)，能參數(shù)明了化就參數(shù)明了化，不能就用函數(shù)命名來區(qū)分~別誤導用戶的使用~
