设计Qt风格的C++API
相當好的關于API設計的文章，Qt的創始人之一寫就，很有啟發，大規模的C++設計會碰到的問題很多，我們可以慢慢想辦法減少這些問題。
原文來自：http://googollee.blog.163.com/blog/static/1159411200811321030894/
設計Qt風格的C++API
翻譯 ??2008-02-13 19:39 ??閱讀1210???評論21 ? 字號： 大 大 ? 中 中 ? 小 小 這是Qt官方發布的文章，覺得對設計API很有借鑒意義。所以順便拿來翻譯了。原文的文內鏈接，因為blog不支持的關系，都沒有起作用，想要html文件的直接問我要吧，或者到 這里 取。（順便做廣告： TopLanguage 是個很好的討論組，歡迎大家去討論關于語言的感受、意見和使用，主持人是 pongba ）作者Matthias Ettrich，譯者Googol Lee，原文地址在這里 。
在奇趣（Trolltech），為了改進Qt的開發體驗，我們做了大量的研究。這篇文章里，我打算分享一些我們的發現，以及一些我們在設計Qt4時用到的原則，并且展示如何把這些原則應用到你的代碼里。
- 好的API的六個特性
- 便利陷阱
- 布爾參數陷阱
- 靜態多態
- 命名的藝術
- 指針還是引用？
- 例子：QProgressBar
- 如何把API設計好
設計應用程序接口，API，是很難的。這是一門和設計語言同樣難的藝術。這里可以選擇太多的原則，甚至有很多原則和其他原則有矛盾。
現在，計算機科學教育把很大的力氣放在算法和數據結構上，而很少關注設計語言和框架背后的原則。這讓應用程序員完全沒有準備去面對越來越重要的任務：創造可重用的組件。
在面向對象語言普及之前，可重用的通用代碼大部分是由庫提供者寫的，而不是應用程序員。在Qt的世界里，這種狀況有了明顯的改善。在任何時候，用 Qt編程就是寫新的組件。一個典型的Qt應用程序至少都會有幾個在程序中反復使用的自定義組件。一般來說，同樣的組件會成為其他應用程序的一部分。 KDE，K桌面環境，走得更遠，用許多追加的庫來擴展Qt，實現了數百個附加類。（一般來說，一個類就是一個可重用組件，原文這里沒有寫清楚。）
但是，一個好的，高效的C++ API是由什么組成的呢？是好還是壞，取決于很多因素——比如，手頭的工作和特定的目標群體。好的API有很多特性，一些特性是大家都想要的，而另一些則是針對特定問題域的。
好的API的六個特性
API是面向程序員的，用來描述提供給最終用戶的GUI是什么樣子。API中的P帶表程序員（Programmer），而不是程序（Program），用來強調API是給程序員用的，給人類的程序員用的。
我們堅信API應該是最小化且完整的，擁有清晰且簡單的語義，直覺化，容易記憶，并且引導人寫出易讀的代碼。
- 最小化： 最小化的API是指一個類盡可能只擁有最少的公開成員且盡可能只擁有最少的類。這個原則可以讓API更簡單易懂，更好記，更容易除錯，且更容易改變。
- 完整的： 完整的API是指要提供所有期望的功能。這個可能與最小化原則相沖突。另外，如果一個成員函數屬于一個不應該屬于的類，很多潛在的使用者都會找不到這個函數。
- 擁有清晰且簡單的語義： 就像其他設計工作一樣，你必須遵守最小驚奇原則（the principle of least surprise）。讓常見的任務簡單易行。不常見的工作可行，但不會讓用戶過分關注。解決特殊問題時，不要讓解決方案沒有必要的過度通用。（比如，Qt3中的QMimeSourceFactory 可以通過調用QImageLoader來實現不同的API。）
- 直覺化： 就像電腦上的其他東西一樣，API必須是直覺化的。不同的經驗和背景會導致在判斷什么是直覺而什么不 是時不同的感覺。如果一個中級用戶不讀文檔就可以使用（a semi-experienced user gets away without reading the documentation，沒懂這里的get away該怎么翻譯），并且一個程序員不懂API就可以理解縮寫的代碼，這種API就是直覺化的。
- 易于記憶： 讓API易于記憶，使用統一且精確的命名方法。使用可識別的模式和概念，并且避免縮寫。
- 引導易讀的代碼（Lead to readable code）： 代碼一經寫就，會讀（并且除錯和修改）多次。易讀的代碼可能會花點時間來寫，但是可以節省產品周期中的其他時間。
最后，記住，不同類型的用戶會用到API的不同部分。雖然簡單的實例化一個Qt類是非常直覺化的，讓資深專家在試圖子類化之前讀一遍文檔，是很合理的。
便利陷阱
這是個常見的誤解：更好的API，用更少的代碼完成一件事。永遠記住代碼一次寫就，之后需要不斷的閱讀并理解。比如：
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");
布爾參數陷阱
布爾參數通常會導致不易讀的代碼。更進一步，給一個已經存在的函數加入一個布爾參數，這常常是個錯誤。在Qt里，一個傳統的例子是repaint()，這個函數帶有一個布爾參數，來標識是否擦除背景（默認擦除）。這讓代碼通常寫成：
widget->repaint(false);初學者很容易把這句話理解成“別重畫”！
這樣做是考慮到布爾參數可以減少一個函數，避免代碼膨脹。事實上，這反而增加了代碼量。有多少Qt用戶真的記住了下面三行程序都是做什么的？
widget->repaint();widget->repaint(true);
widget->repaint(false);
一個好一些的API可能看起來是這樣：
widget->repaint();widget->repaintWithoutErasing();
在Qt4里，我們重新設計了widget，使得用戶不再需要不重畫背景的重畫widget，來解決這個問題。Qt4原生支持雙緩存，廢掉了這個特性。
這里還有一些例子：
widget->setSizePolicy(QSizePolicy ::Fixed,QSizePolicy ::Expanding, true);
textEdit->insert("Where's Waldo?", true, true, false);
QRegExp rx("moc_*.c??", false, true);
一個顯而易見的解決方法是，使用枚舉類型代替布爾參數。這正是我們在Qt4中QString 大小寫敏感時的處理方法。比較：
str.replace("%USER%", user, false); // Qt 3str.replace("%USER%", user, Qt::CaseInsensitive); // Qt 4
靜態多態
相似的類應該含有相似的API。在必要的時候——就是說，需要使用運行時多態的時候——這可以通過繼承實現。但是多態依舊會發生在設計時期。比如，如果你用QListBox 代替QComboBox ，或者用QSlider 代替QSpinBox ，你會發現相似的API使這種替換非常容易。這就是我們所說的“靜態多態”。
靜態多態也使API和程序模式更容易記憶。作為結論，一組相關類使用相似的API，有時要比給每個類提供完美的單獨API，要好。
（譯注：C++ 0x將要引入的concept，就是靜態多態的語法層實現。這個要比單獨的函數名相似更強大且易用。）
命名的藝術
命名，大概是設計API時唯一最重要的問題了。該怎么稱呼這個類？成員函數該叫什么？
通用的命名規則
一些規則通常對所有名字都是有用的。首先，就像我之前提到的，別用縮寫。甚至很明顯的縮寫，比如“prev”表示“previous”從長遠看也是不劃算的，因為用戶必須記住哪些詞是縮寫。
如果API本身不一致，事情自然會變得很糟糕，比如， Qt3有activatePreviousWindow()和fetchPrev()。堅持“沒有縮寫”的規則更容易創建一致的API。
另一個重要但更加微妙的規則是，在設計類的時候，必須盡力保證子類命名空間的干凈。在Qt3里，沒有很好的遵守這個規則。比如，拿QToolButton 來舉例。如果你在Qt3里，對一個QToolButton 調用name()、caption()、text()或者textLabel()，你希望做什么呢？你可以在Qt Designer里拿QToolButton試試：
- name屬性繼承自QObject ，表示一個對象用于除錯和測試的內部名字。
- caption屬性繼承自QWidget ，表示窗口的標題，這個標題在視覺上對QToolButton 沒有任何意義，因為他們總是跟隨父窗口而創建。
- text屬性繼承自QButton ，一般情況下是按鈕上現實的文字，除非useTextLabel為真。
- textLabel在QToolButton 里聲明，并且在useTextLabel為真時顯示在按鈕上。
由于對可讀性的關注，name在Qt4里被稱作objectName，caption變成了windowsTitle，而在QToolButton 里不再有單獨的textLabel屬性。
給類命名
標識一組類而不是單獨給每個類找個恰當的名字。比如，Qt4里所有模式感知項目的視圖類（model-aware item view classes）都擁有-View的后綴（QListView 、QTableView 和QTreeView ），并且對應基于項目的類都用后綴-Widget代替（QListWidget 、QTableWidget 和QTreeWidget ）。
給枚舉類型及其值命名
當聲明枚舉時，時刻記住，在C++（不像Java和C#）中，使用枚舉值不需要類型信息。下面的例子演示了給枚舉值起個太過常用的名字所引起的危害：
namespace Qt{
enum Corner { TopLeft, BottomRight, ... };
enum CaseSensitivity { Insensitive, Sensitive };
...
};
tabWidget->setCornerWidget(widget, Qt::TopLeft);
str.indexOf("$(QTDIR)", Qt::Insensitive);
在最后一行，Insensitive是什么意思？一個用于命名枚舉值的指導思想是，在每個枚舉值里，至少重復一個枚舉類型名中的元素：
namespace Qt{
enum Corner { TopLeftCorner, BottomRightCorner, ... };
enum CaseSensitivity { CaseInsensitive,
CaseSensitive };
...
};
tabWidget->setCornerWidget(widget, Qt::TopLeftCorner);
str.indexOf("$(QTDIR)", Qt::CaseInsensitive);
當枚舉值可以用“或”連接起來當作一個標志時，傳統的做法是將“或”的結果作為一個int保存，這不是類型安全的。Qt4提供了一個模板類 QFlags <T>來實現類型安全，其中T是個枚舉類型。為了方便使用，Qt為很多標志類名提供了typedef，所以你可以使用類型 Qt::Alignment代替QFlags <Qt::AlignmentFlag>。
為了方便，我們給枚舉類型單數的名字（這樣表示枚舉值一次只能有一個標志），而“標志”則使用復數名字。比如：
enum RectangleEdge { LeftEdge, RightEdge, ... };typedef QFlags <RectangleEdge> RectangleEdges;
有些情況下，“標志“類使用了單數的名字。這時，枚舉類使用-Flag做后綴：
enum AlignmentFlag { AlignLeft, AlignTop, ... };typedef QFlags <AlignmentFlag> Alignment;
（這里為啥不是把”標志“類用-Flag做后綴，而是把枚舉值做后綴呢？感覺有點混淆……）
給函數和參數命名
給函數命名的一個規則是，名字要明確體現出這個函數是否有副作用。在Qt3，常數函數QString ::simplifyWhiteSpace()違反了這個原則，因為它返回類一個QString 實例，而不是像名字所提示的那樣，更改了調用這個函數的實例本身。在Qt4，這個函數被重命名為QString ::simplified()。
參數名是程序員的重要信息來源，雖然在使用API時，并不直接展示在代碼里。由于現代IDE在程序員寫代碼時可以自動顯示參數名（就是自動感知或者自動補全之類的功能），值得花時間給頭文件里聲明的參數一個合適的名字，并且在文檔中也使用相同的名字。
給布爾值設置函數（Setter）、提取函數（Getter）和屬性命名
給布爾屬性的設置函數和提取函數一個合適的名字，總是非常痛苦的。提取函數應該叫做checked()還是isChecked()？scrollBarsEnabled()還是areScrollBarEnabled()?
在Qt4里，我們使用下列規則命名提取函數：
- 形容類的屬性使用is-前綴。比如：
- isChecked()
- isDown()
- isEmpty()
- isMovingEnable()
- scrollBarsEnabled() ，而不是areScrollBarsEnabled()
- 動詞類的屬性不使用前綴，且不使用第三人稱（-s）：
- acceptDrops() ，而不是acceptsDrops()
- allColumnsShowFocus()
- 名詞類的屬性，通常沒有前綴：
- autoCompletion() ，而不是isAutoCompletion()
- boundaryChecking()
- isOpenGLAvailable() ，而不是openGL()
- isDialog() ，而不是dialog()
設置函數名字繼承自提取函數名，只是移掉了所有前綴，并使用set-做前綴，比如：setDown()還有setScrollBarsEnabled()。屬性的名字與提取函數相同，只是去掉了前綴。
指針還是引用？
傳出參數的最佳選擇是什么，指針還是引用？
void getHsv(int *h, int *s, int *v) constvoid getHsv(int &h, int &s, int &v) const
大部分C++書推薦在能用引用的地方就用引用，這是因為一般認為引用比指針更“安全且好用”。然而，在奇趣（Trolltech），我們傾向使用指針，因為這讓代碼更易讀。比較：
color.getHsv(&h, &s, &v);color.getHsv(h, s, v);
只有第一行能清楚的說明，在函數調用后，h、s和v將有很大幾率被改動。
例子：QProgressBar
為了展示如何實際應用這些概念，我們將學習Qt3中的API QProgressBar 并和Qt4李相通的API做比較。在Qt3里：
class QProgressBar : public QWidget{
...
public:
int totalSteps() const;
int progress() const;
const QString &progressString() const;
bool percentageVisible() const;
void setPercentageVisible(bool);
void setCenterIndicator(bool on);
bool centerIndicator() const;
void setIndicatorFollowsStyle(bool);
bool indicatorFollowsStyle() const;
public slots:
void reset();
virtual void setTotalSteps(int totalSteps);
virtual void setProgress(int progress);
void setProgress(int progress, int totalSteps);
protected:
virtual bool setIndicator(QString &progressStr,
int progress,
int totalSteps);
...
};
API相當復雜，且不統一。比如，僅從名字reset()并不能理解其作用，setTotalSteps()和setProgress()是緊耦合的。
改進API的關鍵，是注意到QProgressBar 和Qt4的QAbstractSpinBox 類及其子類QSpinBox ，QSlider 和QDial 很相似。解決方法？用minimum、maximum和value代替progress和totalSteps。加入alueChanged()信號。加入setRange()函數。
之后觀察progressString、percentage和indicator實際都指一個東西：在進度條上顯示的文字。一般來說文字是百分比信息，但是也可以使用setIndicator()設為任意字符。下面是新的API：
virtual QString text() const;void setTextVisible(bool visible);
bool isTextVisible() const;
默認的文字信息是百分比信息。文字信息可以藉由重新實現text()而改變。
在Qt3 API中，setCenterIndicator()和setIndicatorFollowStyle()是兩個影響對齊的函數。他們可以方便的由一個函數實現，setAlignment()：
void setAlignment(Qt::Alignment alignment);如果程序員不調用setAlignment()，對齊方式基于當前的風格。對于基于Motif的風格，文字將居中顯示；對其他風格，文字將靠在右邊。
這是改進后的QProgressBar API：
class QProgressBar : public QWidget{
...
public:
void setMinimum(int minimum);
int minimum() const;
void setMaximum(int maximum);
int maximum() const;
void setRange(int minimum, int maximum);
int value() const;
virtual QString text() const;
void setTextVisible(bool visible);
bool isTextVisible() const;
Qt::Alignment alignment() const;
void setAlignment(Qt::Alignment alignment);
public slots:
void reset();
void setValue(int value);
signals:
void valueChanged(int value);
...
};
如何把API設計好（原文是How to Get APIs Right，我總想成We do APIs right……）
API需要質量保證。第一個修訂版不可能是正確的；你必須做測試。寫些用例：看看那些使用了這些API的代碼，并驗證代碼是否易讀。
其他的技巧包括讓別的人分別在有文檔和沒有文檔的情況下，使用這些API；或者為API類寫文檔（包括類的概述和獨立的函數）。
當你卡住時，寫文檔也是一種獲得好名字的方法：僅僅是嘗試把條目（類，函數，枚舉值，等等呢個）寫下來并且使用你寫的第一句話作為靈感。如果你不能 找到一個精確的名字，這常常說明這個條目不應該存在。如果所有前面的事情都失敗了并且你確認這個概念的存在，發明一個新名字。畢竟，“widget”、 “event”、“focus”和“buddy”這些名字就是這么來的。
轉載于:https://www.cnblogs.com/xiaohan-wu/archive/2011/03/02/2167964.html
總結
以上是生活随笔為你收集整理的设计Qt风格的C++API的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： Go to sleep
- 下一篇： linux下phpMyAdmin泛起10