相當(dāng)好的關(guān)于API設(shè)計(jì)的文章，Qt的創(chuàng)始人之一寫就，很有啟發(fā)，大規(guī)模的C++設(shè)計(jì)會(huì)碰到的問題很多，我們可以慢慢想辦法減少這些問題。

原文來自：http://googollee.blog.163.com/blog/static/1159411200811321030894/

設(shè)計(jì)Qt風(fēng)格的C++API

翻譯 ??2008-02-13 19:39 ??閱讀1210???評(píng)論21 ? 字號(hào)： 大 大 ? 中 中 ? 小 小 這是Qt官方發(fā)布的文章，覺得對(duì)設(shè)計(jì)API很有借鑒意義。所以順便拿來翻譯了。原文的文內(nèi)鏈接，因?yàn)閎log不支持的關(guān)系，都沒有起作用，想要html文件的直接問我要吧，或者到 這里 取。（順便做廣告： TopLanguage 是個(gè)很好的討論組，歡迎大家去討論關(guān)于語(yǔ)言的感受、意見和使用，主持人是 pongba ）

作者M(jìn)atthias Ettrich，譯者Googol Lee，原文地址在這里 。

在奇趣（Trolltech），為了改進(jìn)Qt的開發(fā)體驗(yàn)，我們做了大量的研究。這篇文章里，我打算分享一些我們的發(fā)現(xiàn)，以及一些我們?cè)谠O(shè)計(jì)Qt4時(shí)用到的原則，并且展示如何把這些原則應(yīng)用到你的代碼里。

• 好的API的六個(gè)特性
• 便利陷阱
• 布爾參數(shù)陷阱
• 靜態(tài)多態(tài)
• 命名的藝術(shù)
• 指針還是引用？
• 例子：QProgressBar
• 如何把API設(shè)計(jì)好

設(shè)計(jì)應(yīng)用程序接口，API，是很難的。這是一門和設(shè)計(jì)語(yǔ)言同樣難的藝術(shù)。這里可以選擇太多的原則，甚至有很多原則和其他原則有矛盾。

現(xiàn)在，計(jì)算機(jī)科學(xué)教育把很大的力氣放在算法和數(shù)據(jù)結(jié)構(gòu)上，而很少關(guān)注設(shè)計(jì)語(yǔ)言和框架背后的原則。這讓應(yīng)用程序員完全沒有準(zhǔn)備去面對(duì)越來越重要的任務(wù)：創(chuàng)造可重用的組件。

在面向?qū)ο笳Z(yǔ)言普及之前，可重用的通用代碼大部分是由庫(kù)提供者寫的，而不是應(yīng)用程序員。在Qt的世界里，這種狀況有了明顯的改善。在任何時(shí)候，用 Qt編程就是寫新的組件。一個(gè)典型的Qt應(yīng)用程序至少都會(huì)有幾個(gè)在程序中反復(fù)使用的自定義組件。一般來說，同樣的組件會(huì)成為其他應(yīng)用程序的一部分。 KDE，K桌面環(huán)境，走得更遠(yuǎn)，用許多追加的庫(kù)來擴(kuò)展Qt，實(shí)現(xiàn)了數(shù)百個(gè)附加類。（一般來說，一個(gè)類就是一個(gè)可重用組件，原文這里沒有寫清楚。）

但是，一個(gè)好的，高效的C++ API是由什么組成的呢？是好還是壞，取決于很多因素——比如，手頭的工作和特定的目標(biāo)群體。好的API有很多特性，一些特性是大家都想要的，而另一些則是針對(duì)特定問題域的。

好的API的六個(gè)特性

API是面向程序員的，用來描述提供給最終用戶的GUI是什么樣子。API中的P帶表程序員（Programmer），而不是程序（Program），用來強(qiáng)調(diào)API是給程序員用的，給人類的程序員用的。

我們堅(jiān)信API應(yīng)該是最小化且完整的，擁有清晰且簡(jiǎn)單的語(yǔ)義，直覺化，容易記憶，并且引導(dǎo)人寫出易讀的代碼。

• 最小化： 最小化的API是指一個(gè)類盡可能只擁有最少的公開成員且盡可能只擁有最少的類。這個(gè)原則可以讓API更簡(jiǎn)單易懂，更好記，更容易除錯(cuò)，且更容易改變。
• 完整的： 完整的API是指要提供所有期望的功能。這個(gè)可能與最小化原則相沖突。另外，如果一個(gè)成員函數(shù)屬于一個(gè)不應(yīng)該屬于的類，很多潛在的使用者都會(huì)找不到這個(gè)函數(shù)。
• 擁有清晰且簡(jiǎn)單的語(yǔ)義： 就像其他設(shè)計(jì)工作一樣，你必須遵守最小驚奇原則（the principle of least surprise）。讓常見的任務(wù)簡(jiǎn)單易行。不常見的工作可行，但不會(huì)讓用戶過分關(guān)注。解決特殊問題時(shí)，不要讓解決方案沒有必要的過度通用。（比如，Qt3中的QMimeSourceFactory 可以通過調(diào)用QImageLoader來實(shí)現(xiàn)不同的API。）
• 直覺化： 就像電腦上的其他東西一樣，API必須是直覺化的。不同的經(jīng)驗(yàn)和背景會(huì)導(dǎo)致在判斷什么是直覺而什么不 是時(shí)不同的感覺。如果一個(gè)中級(jí)用戶不讀文檔就可以使用（a semi-experienced user gets away without reading the documentation，沒懂這里的get away該怎么翻譯），并且一個(gè)程序員不懂API就可以理解縮寫的代碼，這種API就是直覺化的。
• 易于記憶： 讓API易于記憶，使用統(tǒng)一且精確的命名方法。使用可識(shí)別的模式和概念，并且避免縮寫。
• 引導(dǎo)易讀的代碼（Lead to readable code）： 代碼一經(jīng)寫就，會(huì)讀（并且除錯(cuò)和修改）多次。易讀的代碼可能會(huì)花點(diǎn)時(shí)間來寫，但是可以節(jié)省產(chǎn)品周期中的其他時(shí)間。

最后，記住，不同類型的用戶會(huì)用到API的不同部分。雖然簡(jiǎn)單的實(shí)例化一個(gè)Qt類是非常直覺化的，讓資深專家在試圖子類化之前讀一遍文檔，是很合理的。

便利陷阱

這是個(gè)常見的誤解：更好的API，用更少的代碼完成一件事。永遠(yuǎn)記住代碼一次寫就，之后需要不斷的閱讀并理解。比如：

QSlider *slider = new QSlider (12, 18, 3, 13, Qt::Vertical,
0, "volume");

遠(yuǎn)比下面那樣難讀（甚至難寫）：

QSlider *slider = new QSlider (Qt::Vertical);
slider->setRange(12, 18);
slider->setPageStep(3);
slider->setValue(13);
slider->setObjectName("volume");

布爾參數(shù)陷阱

布爾參數(shù)通常會(huì)導(dǎo)致不易讀的代碼。更進(jìn)一步，給一個(gè)已經(jīng)存在的函數(shù)加入一個(gè)布爾參數(shù)，這常常是個(gè)錯(cuò)誤。在Qt里，一個(gè)傳統(tǒng)的例子是repaint()，這個(gè)函數(shù)帶有一個(gè)布爾參數(shù)，來標(biāo)識(shí)是否擦除背景（默認(rèn)擦除）。這讓代碼通常寫成：

widget->repaint(false);

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

這樣做是考慮到布爾參數(shù)可以減少一個(gè)函數(shù)，避免代碼膨脹。事實(shí)上，這反而增加了代碼量。有多少Q(mào)t用戶真的記住了下面三行程序都是做什么的？

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

一個(gè)好一些的API可能看起來是這樣：

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

在Qt4里，我們重新設(shè)計(jì)了widget，使得用戶不再需要不重畫背景的重畫widget，來解決這個(gè)問題。Qt4原生支持雙緩存，廢掉了這個(gè)特性。

這里還有一些例子：

widget->setSizePolicy(QSizePolicy ::Fixed,
QSizePolicy ::Expanding, true);
textEdit->insert("Where's Waldo?", true, true, false);
QRegExp rx("moc_*.c??", false, true);

一個(gè)顯而易見的解決方法是，使用枚舉類型代替布爾參數(shù)。這正是我們?cè)赒t4中QString 大小寫敏感時(shí)的處理方法。比較：

str.replace("%USER%", user, false); // Qt 3
str.replace("%USER%", user, Qt::CaseInsensitive); // Qt 4

靜態(tài)多態(tài)

相似的類應(yīng)該含有相似的API。在必要的時(shí)候——就是說，需要使用運(yùn)行時(shí)多態(tài)的時(shí)候——這可以通過繼承實(shí)現(xiàn)。但是多態(tài)依舊會(huì)發(fā)生在設(shè)計(jì)時(shí)期。比如，如果你用QListBox 代替QComboBox ，或者用QSlider 代替QSpinBox ，你會(huì)發(fā)現(xiàn)相似的API使這種替換非常容易。這就是我們所說的“靜態(tài)多態(tài)”。

靜態(tài)多態(tài)也使API和程序模式更容易記憶。作為結(jié)論，一組相關(guān)類使用相似的API，有時(shí)要比給每個(gè)類提供完美的單獨(dú)API，要好。

（譯注：C++ 0x將要引入的concept，就是靜態(tài)多態(tài)的語(yǔ)法層實(shí)現(xiàn)。這個(gè)要比單獨(dú)的函數(shù)名相似更強(qiáng)大且易用。）

命名的藝術(shù)

命名，大概是設(shè)計(jì)API時(shí)唯一最重要的問題了。該怎么稱呼這個(gè)類？成員函數(shù)該叫什么？

通用的命名規(guī)則

一些規(guī)則通常對(duì)所有名字都是有用的。首先，就像我之前提到的，別用縮寫。甚至很明顯的縮寫，比如“prev”表示“previous”從長(zhǎng)遠(yuǎn)看也是不劃算的，因?yàn)橛脩舯仨氂涀∧男┰~是縮寫。

如果API本身不一致，事情自然會(huì)變得很糟糕，比如， Qt3有activatePreviousWindow()和fetchPrev()。堅(jiān)持“沒有縮寫”的規(guī)則更容易創(chuàng)建一致的API。

另一個(gè)重要但更加微妙的規(guī)則是，在設(shè)計(jì)類的時(shí)候，必須盡力保證子類命名空間的干凈。在Qt3里，沒有很好的遵守這個(gè)規(guī)則。比如，拿QToolButton 來舉例。如果你在Qt3里，對(duì)一個(gè)QToolButton 調(diào)用name()、caption()、text()或者textLabel()，你希望做什么呢？你可以在Qt Designer里拿QToolButton試試：

• name屬性繼承自QObject ，表示一個(gè)對(duì)象用于除錯(cuò)和測(cè)試的內(nèi)部名字。
• caption屬性繼承自QWidget ，表示窗口的標(biāo)題，這個(gè)標(biāo)題在視覺上對(duì)QToolButton 沒有任何意義，因?yàn)樗麄兛偸歉S父窗口而創(chuàng)建。
• text屬性繼承自QButton ，一般情況下是按鈕上現(xiàn)實(shí)的文字，除非useTextLabel為真。
• textLabel在QToolButton 里聲明，并且在useTextLabel為真時(shí)顯示在按鈕上。

由于對(duì)可讀性的關(guān)注，name在Qt4里被稱作objectName，caption變成了windowsTitle，而在QToolButton 里不再有單獨(dú)的textLabel屬性。

給類命名

標(biāo)識(shí)一組類而不是單獨(dú)給每個(gè)類找個(gè)恰當(dāng)?shù)拿帧１热?#xff0c;Qt4里所有模式感知項(xiàng)目的視圖類（model-aware item view classes）都擁有-View的后綴（QListView 、QTableView 和QTreeView ），并且對(duì)應(yīng)基于項(xiàng)目的類都用后綴-Widget代替（QListWidget 、QTableWidget 和QTreeWidget ）。

給枚舉類型及其值命名

當(dāng)聲明枚舉時(shí)，時(shí)刻記住，在C++（不像Java和C#）中，使用枚舉值不需要類型信息。下面的例子演示了給枚舉值起個(gè)太過常用的名字所引起的危害：

namespace Qt
{
enum Corner { TopLeft, BottomRight, ... };
enum CaseSensitivity { Insensitive, Sensitive };
...
};

tabWidget->setCornerWidget(widget, Qt::TopLeft);

str.indexOf("$(QTDIR)", Qt::Insensitive);

在最后一行，Insensitive是什么意思？一個(gè)用于命名枚舉值的指導(dǎo)思想是，在每個(gè)枚舉值里，至少重復(fù)一個(gè)枚舉類型名中的元素：

namespace Qt
{
enum Corner { TopLeftCorner, BottomRightCorner, ... };
enum CaseSensitivity { CaseInsensitive,
CaseSensitive };
...
};

tabWidget->setCornerWidget(widget, Qt::TopLeftCorner);
str.indexOf("$(QTDIR)", Qt::CaseInsensitive);

當(dāng)枚舉值可以用“或”連接起來當(dāng)作一個(gè)標(biāo)志時(shí)，傳統(tǒng)的做法是將“或”的結(jié)果作為一個(gè)int保存，這不是類型安全的。Qt4提供了一個(gè)模板類 QFlags <T>來實(shí)現(xiàn)類型安全，其中T是個(gè)枚舉類型。為了方便使用，Qt為很多標(biāo)志類名提供了typedef，所以你可以使用類型 Qt::Alignment代替QFlags <Qt::AlignmentFlag>。

為了方便，我們給枚舉類型單數(shù)的名字（這樣表示枚舉值一次只能有一個(gè)標(biāo)志），而“標(biāo)志”則使用復(fù)數(shù)名字。比如：

enum RectangleEdge { LeftEdge, RightEdge, ... };
typedef QFlags <RectangleEdge> RectangleEdges;

有些情況下，“標(biāo)志“類使用了單數(shù)的名字。這時(shí)，枚舉類使用-Flag做后綴：

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

（這里為啥不是把”標(biāo)志“類用-Flag做后綴，而是把枚舉值做后綴呢？感覺有點(diǎn)混淆……）

給函數(shù)和參數(shù)命名

給函數(shù)命名的一個(gè)規(guī)則是，名字要明確體現(xiàn)出這個(gè)函數(shù)是否有副作用。在Qt3，常數(shù)函數(shù)QString ::simplifyWhiteSpace()違反了這個(gè)原則，因?yàn)樗祷仡愐粋€(gè)QString 實(shí)例，而不是像名字所提示的那樣，更改了調(diào)用這個(gè)函數(shù)的實(shí)例本身。在Qt4，這個(gè)函數(shù)被重命名為QString ::simplified()。

參數(shù)名是程序員的重要信息來源，雖然在使用API時(shí)，并不直接展示在代碼里。由于現(xiàn)代IDE在程序員寫代碼時(shí)可以自動(dòng)顯示參數(shù)名（就是自動(dòng)感知或者自動(dòng)補(bǔ)全之類的功能），值得花時(shí)間給頭文件里聲明的參數(shù)一個(gè)合適的名字，并且在文檔中也使用相同的名字。

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

給布爾屬性的設(shè)置函數(shù)和提取函數(shù)一個(gè)合適的名字，總是非常痛苦的。提取函數(shù)應(yīng)該叫做checked()還是isChecked()？scrollBarsEnabled()還是areScrollBarEnabled()?

在Qt4里，我們使用下列規(guī)則命名提取函數(shù)：

• 形容類的屬性使用is-前綴。比如：
  • isChecked()
  • isDown()
  • isEmpty()
  • isMovingEnable()
  另外，應(yīng)用到復(fù)數(shù)名詞的形容類屬性沒有前綴：
  • scrollBarsEnabled() ，而不是areScrollBarsEnabled()
• 動(dòng)詞類的屬性不使用前綴，且不使用第三人稱（-s）：
  • acceptDrops() ，而不是acceptsDrops()
  • allColumnsShowFocus()
• 名詞類的屬性，通常沒有前綴：
  • autoCompletion() ，而不是isAutoCompletion()
  • boundaryChecking()
  有時(shí)，沒有前綴就會(huì)引起誤解，這種情況使用前綴is-：
  • isOpenGLAvailable() ，而不是openGL()
  • isDialog() ，而不是dialog()
  （通過調(diào)用dialogue()方法，正常情況下會(huì)期望返回一個(gè)QDialog *的實(shí)例。）

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

指針還是引用？

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

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

大部分C++書推薦在能用引用的地方就用引用，這是因?yàn)橐话阏J(rèn)為引用比指針更“安全且好用”。然而，在奇趣（Trolltech），我們傾向使用指針，因?yàn)檫@讓代碼更易讀。比較：

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

只有第一行能清楚的說明，在函數(shù)調(diào)用后，h、s和v將有很大幾率被改動(dòng)。

例子：QProgressBar

為了展示如何實(shí)際應(yīng)用這些概念，我們將學(xué)習(xí)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相當(dāng)復(fù)雜，且不統(tǒng)一。比如，僅從名字reset()并不能理解其作用，setTotalSteps()和setProgress()是緊耦合的。

改進(jìn)API的關(guān)鍵，是注意到QProgressBar 和Qt4的QAbstractSpinBox 類及其子類QSpinBox ，QSlider 和QDial 很相似。解決方法？用minimum、maximum和value代替progress和totalSteps。加入alueChanged()信號(hào)。加入setRange()函數(shù)。

之后觀察progressString、percentage和indicator實(shí)際都指一個(gè)東西：在進(jìn)度條上顯示的文字。一般來說文字是百分比信息，但是也可以使用setIndicator()設(shè)為任意字符。下面是新的API：

virtual QString text() const;
void setTextVisible(bool visible);
bool isTextVisible() const;

默認(rèn)的文字信息是百分比信息。文字信息可以藉由重新實(shí)現(xiàn)text()而改變。

在Qt3 API中，setCenterIndicator()和setIndicatorFollowStyle()是兩個(gè)影響對(duì)齊的函數(shù)。他們可以方便的由一個(gè)函數(shù)實(shí)現(xiàn)，setAlignment()：

void setAlignment(Qt::Alignment alignment);

如果程序員不調(diào)用setAlignment()，對(duì)齊方式基于當(dāng)前的風(fēng)格。對(duì)于基于Motif的風(fēng)格，文字將居中顯示；對(duì)其他風(fēng)格，文字將靠在右邊。

這是改進(jìn)后的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設(shè)計(jì)好（原文是How to Get APIs Right，我總想成We do APIs right……）

API需要質(zhì)量保證。第一個(gè)修訂版不可能是正確的；你必須做測(cè)試。寫些用例：看看那些使用了這些API的代碼，并驗(yàn)證代碼是否易讀。

其他的技巧包括讓別的人分別在有文檔和沒有文檔的情況下，使用這些API；或者為API類寫文檔（包括類的概述和獨(dú)立的函數(shù)）。

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

轉(zhuǎn)載于:https://www.cnblogs.com/xiaohan-wu/archive/2011/03/02/2167964.html

總結(jié)

以上是生活随笔為你收集整理的设计Qt风格的C++API的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。