API設計原則

一致、易于掌握和強大的API是Qt最著名的優點之一。此文總結了我們在設計Qt風格API的過程中所積累的訣竅（know-how）。其中許多是通用準則；而其他的則更偏向于約定，遵循這些約定主要是為了與已有的API保持一致。

雖然這些準則主要用于對外的API（public API），但在設計對內的API（private API）時也推薦遵循相同的技巧（techniques），作為開發者之間協作的禮儀（courtesy）。

如有興趣也可以讀一下Jasmin Blanchette的Little Manual of API Design (PDF)或是本文的前身Matthias Ettrich的Designing Qt-Style C++ APIs。

1. 好API的6個特質

API之于程序員就如同圖形界面之于普通用戶（end-user）。API中的『P』實際上指的是『程序員』（Programmer），而不是『程序』（Program），強調的是API是給程序員使用的這一事實。

在第13期Qt季刊，Matthias的關于API設計的文章中提出了觀點：API應該極簡（minimal）且完備（complete）、語義清晰簡單（have clear and simple semantics）、符合直覺（be intuitive）、易于記憶（be easy to memorize）和引導API使用者寫出可讀代碼（lead to readable code）。

1.1 極簡

極簡的API是指每個class的public成員盡可能少，public的class也盡可能少。這樣的API更易理解、記憶、調試和變更。

1.2 完備

完備的API是指期望有的功能都包含了。這點會和保持API極簡有些沖突。如果一個成員函數放在錯誤的類中，那么這個函數的潛在用戶就會找不到，這也是違反完備性的。

1.3 語義清晰簡單

就像其他的設計一樣，我們應該遵守最少意外原則（the principle of least surprise）。好的API應該可以讓常見的事完成的更簡單，并有可以完成不常見的事的可能性，但是卻不會關注于那些不常見的事。解決的是具體問題；當沒有需求時不要過度通用化解決方案。（舉個例子，在Qt 3中，QMimeSourceFactory不應命名成QImageLoader并有不一樣的API。）

1.4 符合直覺

就像計算機里的其他事物一樣，API應該符合直覺。對于什么是符合直覺的什么不符合，不同經驗和背景的人會有不同的看法。API符合直覺的測試方法：經驗不很豐富的用戶不用閱讀API文檔就能搞懂API，而且程序員不用了解API就能看明白使用API的代碼。

1.5 易于記憶

為使API易于記憶，API的命名約定應該具有一致性和精確性。使用易于識別的模式和概念，并且避免用縮寫。

1.6 引導API使用者寫出可讀代碼

代碼只寫一次，卻要多次的閱讀（還有調試和修改）。寫出可讀性好的代碼有時候要花費更多的時間，但對于產品的整個生命周期來說是節省了時間的。

最后，要記住的是，不同的用戶會使用API的不同部分。盡管簡單使用單個Qt類的實例應該符合直覺，但如果是要繼承一個類，讓用戶事先看好文檔是個合理的要求。

2. 靜態多態

相似的類應該有相似的API。在繼承（inheritance）合適時可以用繼承達到這個效果，即運行時多態。然而多態也發生在設計階段。例如，如果你用QProgressBar替換QSlider，或是用QString替換QByteArray，你會發現API的相似性使的替換很容易。這即是所謂的『靜態多態』（static polymorphism）。

靜態多態也使記憶API和編程模式更加容易。因此，一組相關的類有相似的API有時候比每個類都有各自的一套API更好。

一般來說，在Qt中，如果沒有足夠的理由要使用繼承，我們更傾向于用靜態多態。這樣可以減少Qtpublic類的個數，也使剛學習Qt的用戶在翻看文檔時更有方向感。

2.1 好的案例

QDialogButtonBox與QMessageBox，在處理按鈕（addButton()、setStandardButtons()等等）上有相似的API，不需要繼承某個QAbstractButtonBox類。

2.2 差的案例

QTcpSocket與QUdpSocket都繼承了QAbstractSocket，這兩個類的交互行為的模式（mode of interaction）非常不同。似乎沒有什么人以通用和有意義的方式用過QAbstractSocket指針（或者能以通用和有意義的方式使用QAbstractSocket指針）。

2.3 值得斟酌的案例

QBoxLayout是QHBoxLayout與QVBoxLayout的父類。好處：可以在工具欄上使用QBoxLayout，調用setOrientation()使其變為水平/垂直。壞處：要多一個類，并且有可能導致用戶寫出這樣沒什么意義的代碼，((QBoxLayout *)hbox)->setOrientation(Qt::Vertical)。