設計Qt風格的C++API

原文地址：http://doc.qt.digia.com/qq/qq13-apis.html

在奇趣（Trolltech），為了改進Qt的開發體驗，我們做了大量的研究。這篇文章里，我打算分享一些我們的發現，以及一些我們在設計Qt4時用到的原則，並且展示如何把這些原則應用到你的代碼里。

優秀API的六個特性

便利陷阱

布爾參數陷阱

靜態多態

命名的藝術

指針還是引用？

案例分析：QProgressBar

如何把API設計好

設計應用程序接口(APIs)是有難度的，這是一門和設計語言同樣難的藝術。要遵循許多不同的原則，這些原則中的許多還彼此沖突。

現在，計算機科學教育把很大的力氣放在算法和數據結構上，而很少關注設計語言和框架背后的原則。這讓應用程序員完全沒有准備去面對越來越重要的任務：創造可重用的組件。

在面向對象語言普及之前，可重用的通用代碼大部分是由庫提供者寫的，而不是應用程序員。在Qt的世界里，這種狀況有了明顯的改善。在任何時候，用Qt編程 就是寫新的組件。一個典型的Qt應用程序至少都會有幾個在程序中反復使用的自定義組件。一般來說，同樣的組件會成為其他應用程序的一部分。KDE，K桌面環境，走得更遠，用許多追加的庫來擴展Qt，實現了數百個附加類。

但是一個優秀，高效的C++ API究竟是怎樣的呢？它的好壞取決於許多因素，比如說，手頭上的任務和特定目標群體。優秀的API具有很多特性，它們中的一些是普遍所要期望的，另一些是針對特定問題領域的。

優秀API的六個特性

API對於程序員就相當於GUI對於最終用戶。API中“P”代表程序員(Programmer)，而不是程序(Program)，強調這一點是為了說明API是讓程序員使用的，程序員是人而不機器。

我們認為APIs應當精簡而完備，具有清晰簡單的語義，直觀、易記且應使代碼具有可讀性。

精簡性：精簡的API具有盡可能少的類和公共成員。這使得理解，記憶，調試，更改API更加容易。

完備性：是指要提供所有期望的功能。這可能與精簡性原則相沖突。還有，如果成員函數放在不相匹配的類中，那么許多要使用這個功能函數的潛在用戶會找不到它。

擁有清晰且簡單的語義：就像其他設計工作一樣，你必須遵守最小驚奇原則（the principle of least surprise）。讓常見的任務簡單易行。不常見的工作可行，但不會讓用戶過分關注。解決特殊問題時，不要讓解決方案沒有必要的過度通用。（比如，Qt3中的QMimeSourceFactory可以通過調用QImageLoader來實現不同的API。）

直觀性： 就像計算機上的其他東西一樣，API應具有直觀性。不同的經驗和背景會導致對哪些是直觀，哪些不是直觀的不同看法。如果一個中級用戶不讀文檔就可以使用（a semi-experienced user gets away without reading the documentation），並且對並不知曉這個API的程序員來說，他能夠理解使用了這個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");

布爾參數陷阱

布爾參數常常導致難以閱讀的代碼。特別地，增加某個bool參數到現存的函數一般都會是個錯誤的決定。在Qt中，傳統的例子是repaint()，它帶有一個可選的布爾參數，來指定背景是否刪除(默認是刪除)。這就導致了代碼會像這樣子：

widget->repaint(false);

初學者很容易把這句話理解成“別重畫”！

這樣做是考慮到使用布爾參數可以減少一個函數，避免代碼膨脹。事實上，這反而增加了代碼量。有多少Qt用戶真的記住了下面三行程序都是做什么的？

widget->repaint();
widget->repaint(true);
widget->repaint(false);

一個好一些的API可能看起來是這樣：

widget->repaint();
widget->repaintWithoutErasing();

在Qt 4中，我們解決這個問題的辦法是，簡單地去除掉不刪除widget而進行重繪的可能性。Qt 4對雙重緩沖的原生支持，會使這功能被廢棄掉。

這里還有一些例子：

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 3
str.replace("%USER%", user, Qt::CaseInsensitive); // Qt 4

靜態多態

相似的類應該有相似的API。在某種程度上，這能用繼承來實現，也就是運用運行時多態機制。但是多態也可以發生在設計時期。比如，如果你用QListBox代替QComboBox，或者用QSlider代替QSpinBox，你會發現相似的API使這種替換非常容易。這就是我們所說的“靜態多態”。

靜態多態也使API和程序模式更容易記憶。作為結論，一組相關類使用相似的API，有時要比給每個類提供完美的單獨API，要好。

命名的藝術

命名有時候是設計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;

在某些情況下，"flags"類型有單數形式的名稱。在這種情況下，枚舉類型以Flag后綴標識：

enum AlignmentFlag { AlignLeft, AlignTop, ... };
typedef QFlags<AlignmentFlag> Alignment;

函數和參數的命名

給函數命名的一個規則是，名字要明確體現出這個函數是否有副作用。在Qt3，常數函數QString::simplifyWhiteSpace()違反了這個原則，因為它返回類一個QString實例，而不是像名字所提示的那樣，更改了調用這個函數的實例本身。在Qt4，這個函數被重命名為QString::simplified()。

參數名對於程序員來說是重要的信息來源,即使它們不出現在調用API的代碼中.既然現代的IDE會在程序員編碼時顯示這些參數，所以非常值得在頭文件中給這些參數取恰當的名字，並且在文檔中也使用相同的名字。

給布爾值設置函數（Setter）、提取函數（Getter）和屬性命名

給布爾屬性的設置函數和提取函數取一個合適的名字，總是特別困難的。提取函數應該叫做checked()還是isChecked()？scrollBarsEnabled()還是areScrollBarEnabled()？

在Qt4里，我們使用下列規則命名提取函數：

（1）形容類的屬性使用is-前綴。比如：

isChecked()

isDown()

isEmpty()

isMovingEnable()

另外，應用到復數名詞的形容類屬性沒有前綴：

scrollBarsEnabled()，而不是areScrollBarsEnabled()

（2）動詞類的屬性不使用前綴，且不使用第三人稱（-s）：

acceptDrops()，而不是acceptsDrops()

allColumnsShowFocus()

（3）名詞類的屬性，通常沒有前綴：

autoCompletion()，而不是isAutoCompletion()

boundaryChecking()

有時，沒有前綴就會引起誤解，這種情況使用前綴is-：

isOpenGLAvailable()，而不是openGL()

isDialog()，而不是dialog()

(如果函數叫做dialog()，我們通常會認定它會返回QDialog*類型)

設置函數名字可以從提取函數名推出來，只是移掉了所有前綴，並使用set-做前綴，比如：setDown()還有setScrollBarsEnabled()。屬性的名字與提取函數相同，只是去掉了“is”前綴。

指針還是引用？

傳出參數的最佳選擇是什么，指針還是引用？

void getHsv(int *h, int *s, int *v) const
void getHsv(int &h, int &s, int &v) const

大部分C++書推薦在能用引用的地方就用引用，這是因為一般認為引用比指針更“安全且好用”。然而，在奇趣（Trolltech），我們傾向使用指針，因為這讓代碼更易讀。比較：

color.getHsv(&h, &s, &v);
color.getHsv(h, s, v);

只有第一行能清楚的說明，在函數調用后，h、s和v將有很大幾率被改動。

案例分析：QProgressBar

為了在實際代碼中說明這些概念，我們以QProgressBar在Qt3和Qt4中的比較進行研究。在Qt 3中：

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設計好

API需要質量保證。第一個修訂版不可能是正確的；你必須做測試。寫些用例：看看那些使用了這些API的代碼，並驗證代碼是否易讀。

其他的技巧包括讓別人分別在有文檔和沒有文檔的情況下，使用這些API並且為API類寫文檔（包括類的概述和獨立的函數）。

當你卡住時，寫文檔也是一種獲得好名字的方法：僅僅是嘗試把條目（類，函數，枚舉值，等等呢個）寫下來並且使用你寫的第一句話作為靈感。如果你不能找到一 個精確的名字，這常常說明這個條目不應該存在。如果所有前面的事情都失敗了並且你確認這個概念的存在，發明一個新名字。畢竟，“widget”、 “event”、“focus”和“buddy”這些名字就是這么來的。

Reference:

[1]: http://my.oschina.net/qihh/blog/56686

[2]: http://www.cppblog.com/len/archive/2008/05/11/49563.html#sixcharacteristicsofgoodapis