相當好的關于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 3
str.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()
  有時，沒有前綴就會引起誤解，這種情況使用前綴is-：
  • isOpenGLAvailable() ，而不是openGL()
  • isDialog() ，而不是dialog()
  （通過調用dialogue()方法，正常情況下會期望返回一個QDialog *的實例。）

設置函數名字繼承自提取函數名，只是移掉了所有前綴，并使用set-做前綴，比如：setDown()還有setScrollBarsEnabled()。屬性的名字與提取函數相同，只是去掉了前綴。

指針還是引用？

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

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

為了展示如何實際應用這些概念，我們將學習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的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。