f1中的参数所指向的对象应该由谁来删除呢？调用者还是被调用者？如果不看程序文档的话，无法知道这一点。f2函数也存在同样的问题。

   用auto_ptr可以消除这种歧义性：

  
      尽管如此，auto_ptr的“所有权转移”语义还是会带来副作用，因为会修改原值的常量拷贝违背了一般的设计原则，它也许会在你意想不到的情况下就把对象转移了。它也不能用于标准容器中。
   所以auto_ptr在新的标准库已经不再推荐使用。取而代之的是unique_ptr。unique_ptr与auto_ptr类似，但限制了auto_ptr的拷贝行为。同时，像上面举的例子一样，unique_ptr可以作为函数的参数和返回值使用。这是因为C++增加了一个新的特征：右值引用。

   shared_ptr也进入了标准库。对于引用计数的智能指针而言，循环引用是一个大问题。标准库为此把shared_ptr定义为强引用指针，它还实现了一个弱引用指针weak_ptr。显然，标准库并没有从根本上解决循环引用的问题，它把这个问题交给了程序员。在一个简单的系统中，你可以区分使用shared_ptr和weak_ptr，以此来避免出现循环引用。但是在一个大的对象系统中，有时还是容易出错。循环引用的问题，严重减弱了shared_ptr的可用性。

   那么能不能自动检测是否出现循环引用呢？事实上，对于shared_ptr这种使用非侵入式策略实现的智能指针，是很难实现自动检测的。但是如果采用侵入式设计，我们可以引入一些接口，来解决这个问题。循环引用的检测，实际上是图论中的回路检测问题。

      本文由eXile 原创，转载请表明原贴地址。 http://www.cppblog.com/eXile/。

Google C++ Testing Framework Primer

翻译：Ray Li (ray.leex@gmail.com)
修改日期：2008年7月6日
原文参见：http://code.google.com/p/googletest/wiki/GoogleTestPrimer

译文地址：http://www.javaeye.com/topic/212024

Introduction：为什么需要Google C++ 测试框架？

Google C++ 测试框架帮助你更好地编写C++测试。

无论你是在Linux，Windows，还是Mac环境下工作，只要你编写C++代码，Google 测试框架都可以帮上忙。

那么，哪些因素才能构成一个好的测试？以及，Google C++ 测试框架怎样满足这些因素？我们相信：

1. 测试应该是独立、可重复的。因为其他测试成功或失败而导致我们要对自己的测试进行debug是非常痛苦的。Google C++ 测试框架通过将每个测试在不同的对象中运行，使得测试分离开来。当一个测试失败时，Google C++ 测试框架允许你独立运行它以进行快速除错。
2. 测试应该能够被很好地组织，并反映被测代码的结构。Google C++ 测试框架将测试组织成测试案例，案例中的测试可以共享数据和程序分支。这样一种通用模式能够很容易辨识，使得我们的测试容易维护。当开发人员在项目之间转换，开始在一个新的代码基上开始工作时，这种一致性格外有用。
3. 测试应该是可移植、可重用的。开源社区有很多平台独立的代码，它们的测试也应该是平台独立的。除开一些特殊情况，Google C++ 测试框架运行在不同的操作系统上、与不同的编译器（gcc、icc、MSVC）搭配，Google C++ 测试框架的测试很容易与不同的配置一起工作。
4. 当测试失败时，应该提供尽可能多的、关于问题的信息。Google C++ 测试框架在第一个测试失败时不会停下来。相反，它只是将当前测试停止，然后继续接下来的测试。你也可以设置对一些非致命的错误进行报告，并接着进行当前的测试。这样，你就可以在一次“运行-编辑-编译”循环中检查到并修复多个bug。
5. 测试框架应该能将测试编写人员从一些环境维护的工作中解放出来，使他们能够集中精力于测试的内容。Google C++ 测试框架自动记录下所有定义好的测试，不需要用户通过列举来指明哪些测试需要运行。
6. 测试应该快速。使用Google C++ 测试框架，你可以重用多个测试的共享资源，一次性完成设置/解除设置，而不用使一个测试去依赖另一测试。

因为Google C++ 测试框架基于著名的xUnit架构，如果你之前使用过JUnit或PyUnit的话，你将会感觉非常熟悉。如果你没有接触过这些测试框架，它也只会占用你大约10分钟的时间来学习基本概念和上手。所以，让我们开始吧！

Note：本文偶尔会用“Google Test”来代指“Google C++ 测试框架”。

基本概念

使用Google Test时，你是从编写断言开始的，而断言是一些检查条件是否为真的语句。一个断言的结果可能是成功、非致命失败，或者致命失败。如果一个致命失败出现，他会结束当前的函数；否则，程序继续正常运行。

测试使用断言来验证被测代码的行为。如果一个测试崩溃或是出现一个失败的断言，那么，该测试失败；否则该测试成功。

一个测试案例（test case）包含了一个或多个测试。你应该将自己的测试分别归类到测试案例中，以反映被测代码的结构。当测试案例中的多个测试需要共享通用对象和子程序时，你可以把他们放到一个测试固件（test fixture）类中。

一个测试程序可以包含多个测试案例。

从编写单个的断言开始，到创建测试和测试案例，我们将会介绍怎样编写一个测试程序。

断言

Google Test中的断言是一些与函数调用相似的宏。要测试一个类或函数，我们需要对其行为做出断言。当一个断言失败时，Google Test会在屏幕上输出该代码所在的源文件及其所在的位置行号，以及错误信息。也可以在编写断言时，提供一个自定义的错误信息，这个信息在失败时会被附加在Google Test的错误信息之后。

断言常常成对出现，它们都测试同一个类或者函数，但对当前功能有着不同的效果。ASSERT_*版本的断言失败时会产生致命失败，并结束当前函数。EXPECT_*版本的断言产生非致命失败，而不会中止当前函数。通常更推荐使用EXPECT_*断言，因为它们运行一个测试中可以有不止一个的错误被报告出来。但如果在编写断言如果失败，就没有必要继续往下执行的测试时，你应该使用ASSERT_*断言。

因为失败的ASSERT_*断言会立刻从当前的函数返回，可能会跳过其后的一些的清洁代码，这样也许会导致空间泄漏。根据泄漏本身的特质，这种情况 也许值得修复，也可能不值得我们关心——所以，如果你得到断言错误的同时，还得到了一个堆检查的错误，记住上面我们所说的这一点。

要提供一个自定义的错误消息，只需要使用<<操作符，或一个<<操作符的序列，将其输入到框架定义的宏中。下面是一个例子：

ASSERT_EQ(x.size(), y.size()) << "Vectors x and y are of unequal length";
for (int i = 0; i < x.size(); ++i) {
EXPECT_EQ(x[i], y[i]) << "Vectors x and y differ at index " << i;
}

任何能够被输出到ostream中的信息都可以被输出到一个断言宏中——特别是C字符串和string对象。如果一个宽字符串 （wchar_t*，windows上UNICODE模式TCHAR*或std::wstring）被输出到一个断言中，在打印时它会被转换成UTF-8 编码。

基本断言

下面这些断言实现了基本的true/false条件测试。

记住，当它们失败时，ASSERT_*产生一个致命失败并从当前函数返回，而EXCEPT_*产生一个非致命失败，允许函数继续运行。在两种情况下，一个断言失败都意味着它所包含的测试失败。

有效平台：Linux、Windows、Mac。

二进制比较

本节描述了比较两个值的一些断言。

在出现失败事件时，Google Test会将两个值（Val1和Val2）都打印出来。在ASSERT_EQ*和EXCEPT_EQ*断言（以及我们随后介绍类似的断言）中，你应该把你希望测试的表达式放在actual（实际值）的位置上，将其期望值放在expected（期望值）的位置上，因为Google Test的测试消息为这种惯例做了一些优化。

参数值必须是可通过断言的比较操作符进行比较的，否则你会得到一个编译错误。参数值还必须支持<<操作符来将值输入到ostream中。所有的C++内置类型都支持这一点。

这些断言可以用于用户自定义的型别，但你必须重载相应的比较操作符（如==、<等）。如果定义有相应的操作符，推荐使用ASSERT_*()宏，因为它们不仅会输出比较的结果，还会输出两个比较对象。

参数表达式总是只被解析一次。因此，参数表达式有一定的副作用（side effect，这里应该是指编译器不同，操作符解析顺序的不确定性）也是可以接受的。但是，同其他普通C/C++函数一样，参数表达式的解析顺序是不确定的（如，一种编译器可以自由选择一种顺序来进行解析），而你的代码不应该依赖于某种特定的参数解析顺序。

ASSERT_EQ()对指针进行的是指针比较。即，如果被用在两个C字符串上，它会比较它们是否指向同样的内存地址，而不是它们所指向的字符串是否有相同值。所以，如果你想对两个C字符串（例如，const char*）进行值比较，请使用ASSERT_STREQ()宏，该宏会在后面介绍到。特别需要一提的是，要验证一个C字符串是否为空（NULL），使用ASSERT_STREQ(NULL, c_string)。但是要比较两个string对象时，你应该使用ASSERT_EQ。

本节中介绍的宏都可以处理窄字符串对象和宽字符串对象（string和wstring）。

有效平台：Linux、Windows、Mac。

字符串比较

该组断言用于比较两个C字符串。如果你想要比较两个string对象，相应地使用EXPECT_EQ、EXPECT_NE等断言。

注意断言名称中出现的“CASE”意味着大小写被忽略了。

*STREQ*和*STRNE*也接受宽字符串（wchar_t*）。如果两个宽字符串比较失败，它们的值会做为UTF-8窄字符串被输出。

一个NULL空指针和一个空字符串会被认为是不一样的。

有效平台：Linux、Windows、Mac。

参见：更多的字符串比较的技巧（如子字符串、前缀和正则表达式匹配），请参见[Advanced Guide Advanced Google Test Guide]。

简单的测试

要创建一个测试：

1. 使用TEST（）宏来定义和命名一个测试函数，它们是一些没有返回值的普通C++函数。
2. 在这个函数中，与你想要包含的其它任何有效C++代码一起，使用Google Test提供的各种断言来进行检查。
3. 测试的结果由其中的断言决定；如果测试中的任意断言失败（无论是致命还是非致命），或者测试崩溃，那么整个测试就失败了。否则，测试通过。 

TEST(test_case_name, test_name) {
... test body ...
}

TEST（）的参数是从概括到特殊的。第一个参数是测试案例的名称，第二个参数是测试案例中的测试的名称。记住，一个测试案例可以包含任意数量的独立测试。一个测试的全称包括了包含它的测试案例名称，及其独立的名称。不同测试案例中的独立测试可以有相同的名称。

举例来说，让我们看一个简单的整数函数：

int Factorial(int n); // 返回n的阶乘

这个函数的测试案例应该看起来像是：

// 测试0的阶乘
TEST(FactorialTest, HandlesZeroInput) {
EXPECT_EQ(1, Factorial(0));
}
// 测试正数的阶乘
TEST(FactorialTest, HandlesPositiveInput) {
EXPECT_EQ(1, Factorial(1));
EXPECT_EQ(2, Factorial(2));
EXPECT_EQ(6, Factorial(3));
EXPECT_EQ(40320, Factorial(8));
}

Google Test根据测试案例来分组收集测试结果，因此，逻辑相关的测试应该在同一测试案例中；换句话说，它们的TEST（）的第一个参数应该是一样的。在上面的例子中，我们有两个测试，HandlesZeroInput和HandlesPostiveInput，它们都属于同一个测试案例FactorialTest。

有效平台：Linux、Windows、Mac。

测试固件（Test Fixtures，又做测试夹具、测试套件）：在多个测试中使用同样的数据配置

当你发现自己编写了两个或多个测试来操作同样的数据，你可以采用一个测试固件。它让你可以在多个不同的测试中重用同样的对象配置。

要创建测试固件，只需：

1. 创建一个类继承自testing::Test。将其中的成员声明为protected:或是public:，因为我们想要从子类中存取固件成员。
2. 在该类中声明你计划使用的任何对象。
3. 如果需要，编写一个默认构造函数或者SetUp()函数来为每个测试准备对象。常见错误包括将SetUp()拼写为Setup()（小写了u）——不要让它发生在你身上。
4. 如果需要，编写一个析构函数或者TearDown()函数来释放你在SetUp()函数中申请的资源。要知道什么时候应该使用构造函数/析构函数，什么时候又应该使用SetUp()/TearDown()函数，阅读我们的FAQ。
5. 如果需要，定义你的测试所需要共享的子程序。

当我们要使用固件时，使用TEST_F()替换掉TEST()，它允许我们存取测试固件中的对象和子程序：

TEST_F(test_case_name, test_name) {
... test body ...
}

与TEST()一样，第一个参数是测试案例的名称，但对TEST_F()来说，这个名称必须与测试固件类的名称一些。你可能已经猜到了：_F正是指固件。

不幸地是，C++宏系统并不允许我们创建一个单独的宏来处理两种类型的测试。使用错误的宏会导致编译期的错误。

而且，你必须在TEST_F()中使用它之前，定义好这个测试固件类。否则，你会得到编译器的报错：“virtual outside class declaration”。

对于TEST_F()中定义的每个测试，Google Test将会：

1. 在运行时创建一个全新的测试固件
2. 马上通过SetUp()初始化它，
3. 运行测试
4. 调用TearDown()来进行清理工作
5. 删除测试固件。注意，同一测试案例中，不同的测试拥有不同的测试固件。Google Test在创建下一个测试固件前总是会对现有固件进行删除。Google Test不会对多个测试重用一个测试固件。测试对测试固件的改动并不会影响到其他测试。

例如，让我们为一个名为Queue的FIFO队列类编写测试，该类的接口如下：

template <typename E> // E为元素类型
class Queue {
public:
Queue();
void Enqueue(const E& element);
E* Dequeue(); // 返回 NULL 如果队列为空.
size_t size() const;
...
};

首先，定义一个固件类。习惯上，你应该把它的名字定义为FooTest，这里的Foo是被测试的类。

class QueueTest : public testing::Test {
protected:
virtual void SetUp() {
q1_.Enqueue(1);
q2_.Enqueue(2);
q2_.Enqueue(3);
}
// virtual void TearDown() {}
Queue<int> q0_;
Queue<int> q1_;
Queue<int> q2_;
};

在这个案例中，我们不需要TearDown()，因为每个测试后除了析构函数外不需要进行其它的清理工作了。

接下来我们使用TEST_F()和这个固件来编写测试。

TEST_F(QueueTest, IsEmptyInitially) {
EXPECT_EQ(0, q0_.size());
}
TEST_F(QueueTest, DequeueWorks) {
int* n = q0_.Dequeue();
EXPECT_EQ(NULL, n);
n = q1_.Dequeue();
ASSERT_TRUE(n != NULL);
EXPECT_EQ(1, *n);
EXPECT_EQ(0, q1_.size());
delete n;
n = q2_.Dequeue();
ASSERT_TRUE(n != NULL);
EXPECT_EQ(2, *n);
EXPECT_EQ(1, q2_.size());
delete n;
}

上面这段代码既使用了ASSERT_*断言，又使用了EXPECT_*断言。经验上讲，如果你想要断言失败后，测试能够继续进行以显示更多的错误 时，你应该使用EXPECT_*断言；使用ASSERT_*如果该断言失败后继续往下执行毫无意义。例如，Dequeue测试中的第二个断言是 ASSERT_TURE(n!= NULL)，因为我们随后会n指针解引用，如果n指针为空的话，会导致一个段错误。

当这些测试开始时，会发生如下情况：

1. Google Test创建一个QueueTest对象（我们把它叫做t1）。
2. t1.SetUp()初始化t1。
3. 第一个测试（IsEmptyInitiallly）在t1上运行。
4. 测试完成后，t1.TearDown()进行一些清理工作。
5. t1被析构。
6. 以上步骤在另一个QueueTest对象上重复进行，这回会运行DequeueWorks测试。

有效平台：Linux、Windows、Mac。

注意：当一个测试对象被构造时，Google Test会自动地保存所有的Google Test变量标识，对象析构后进行恢复。

调用测试

TEST()和TEST_F()向Google Test隐式注册它们的测试。因此，与很多其他的C++测试框架不同，你不需要为了运行你定义的测试而将它们全部再列出来一次。

在定义好测试后，你可以通过RUN_ALL_TESTS()来运行它们，如果所有测试成功，该函数返回0，否则会返回1.注意RUN_ALL_TESTS()会运行你链接到的所有测试——它们可以来自不同的测试案例，甚至是来自不同的文件。

当被调用时，RUN_ALL_TESTS()宏会：

1. 保存所有的Google Test标志。
2. 为一个侧测试创建测试固件对象。
3. 调用SetUp()初始化它。
4. 在固件对象上运行测试。
5. 调用TearDown()清理固件。
6. 删除固件。
7. 恢复所有Google Test标志的状态。
8. 重复上诉步骤，直到所有测试完成。

此外，如果第二步时，测试固件的构造函数产生一个致命错误，继续执行3至5部显然没有必要，所以它们会被跳过。与之相似，如果第3部产生致命错误，第4部也会被跳过。

重要：你不能忽略掉RUN_ALL_TESTS()的返回值，否则gcc会报一个编译错误。这样设计的理由是自动化测试服务会根据测试退出返回码来决定一个测试是否通过，而不是根据其stdout/stderr输出；因此你的main()函数必须返回RUN_ALL_TESTS()的值。

而且，你应该只调用RUN_ALL_TESTS()一次。多次调用该函数会与Google Test的一些高阶特性（如线程安全死亡测试thread-safe death tests）冲突，因而是不被支持的。

有效平台：Linux、Windows、Mac。

编写main()函数

你可以从下面这个样板开始:

#include "this/package/foo.h"
#include <gtest/gtest.h>
namespace {
// 测试Foo类的测试固件
class FooTest : public testing::Test {
protected:
// You can remove any or all of the following functions if its body
// is empty.
FooTest() {
// You can do set-up work for each test here.
}
virtual ~FooTest() {
// You can do clean-up work that doesn't throw exceptions here.
}
// If the constructor and destructor are not enough for setting up
// and cleaning up each test, you can define the following methods:
virtual void SetUp() {
// Code here will be called immediately after the constructor (right
// before each test).
}
virtual void TearDown() {
// Code here will be called immediately after each test (right
// before the destructor).
}
// Objects declared here can be used by all tests in the test case for Foo.
};
// Tests that the Foo::Bar() method does Abc.
TEST_F(FooTest, MethodBarDoesAbc) {
const string input_filepath = "this/package/testdata/myinputfile.dat";
const string output_filepath = "this/package/testdata/myoutputfile.dat";
Foo f;
EXPECT_EQ(0, f.Bar(input_filepath, output_filepath));
}
// Tests that Foo does Xyz.
TEST_F(FooTest, DoesXyz) {
// Exercises the Xyz feature of Foo.
}
}  // namespace
int main(int argc, char **argv) {
testing::InitGoogleTest(&argc, argv);
return RUN_ALL_TESTS();
}

testing::InitGoogleTest()函数负责解析命令行传入的Google Test标志，并删除所有它可以处理的标志。这使得用户可以通过各种不同的标志控制一个测试程序的行为。关于这一点我们会在GTestAdvanced中讲到。你必须在调用RUN_ALL_TESTS()之前调用该函数，否则就无法正确地初始化标示。

在Windows上InitGoogleTest()可以支持宽字符串，所以它也可以被用在以UNICODE模式编译的程序中。

进阶阅读

恭喜你！你已经学到了一些Google Test基础。你可以从编写和运行几个Google Test测试开始，再阅读一下GoogleTestSamples，或是继续研究GoogleTestAdvancedGuide，其中描述了很多更有用的Google Test特性。

已知局限

Google Test被设计为线程安全的。但是，我们还没有时间在各种平台上实现同步原语（synchronization primitives）。因此，目前从两个线程同时使用Google Test断言是不安全的。由于通常断言是在主线程中完成的，因此在大多数测试中这都不算问题。如果你愿意帮忙，你可以试着在gtest-port.h中实现必要的同步原语。

在奇趣（Trolltech），为了改进Qt的开发体验，我们做了大量的研究。这篇文章里，我打算分享一些我们的发现，以及一些我们在设计Qt4时用到的原则，并且展示如何把这些原则应用到你的代码里。

• 好的API的六个特性
• 便利陷阱
• 布尔参数陷阱
• 静态多态
• 命名的艺术
• 指针还是引用？
• 例子：QProgressBar
• 如何把API设计好

设计应用程序接口，API，是很难的。这是一门和设计语言同样难的艺术。这里可以选择太多的原则，甚至有很多原则和其他原则有矛盾。

现在，计算机科学教育把很大的力气放在算法和数据结构上，而很少关注设计语言和框架背后的原则。这让应用程序员完全没有准备去面对越来越重要的任务：创造可重用的组件。

在面向对象语言普及之前，可重用的通用代码大部分是由库提供者写的，而不是应用程序员。在Qt的世界里，这种状况有了明显的改善。在任何时候，用Qt编程就是写新的组件。一个典型的Qt应用程序至少都会有几个在程序中反复使用的自定义组件。一般来说，同样的组件会成为其他应用程序的一部分。KDE，K桌面环境，走得更远，用许多追加的库来扩展Qt，实现了数百个附加类。（一般来说，一个类就是一个可重用组件，原文这里没有写清楚。）

但是，一个好的，高效的C++ 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将有很大几率被改动。

为了展示如何实际应用这些概念，我们将学习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需要质量保证。第一个修订版不可能是正确的；你必须做测试。写些用例：看看那些使用了这些API的代码，并验证代码是否易读。

其他的技巧包括让别的人分别在有文档和没有文档的情况下，使用这些API；或者为API类写文档（包括类的概述和独立的函数）。

当你卡住时，写文档也是一种获得好名字的方法：仅仅是尝试把条目（类，函数，枚举值，等等呢个）写下来并且使用你写的第一句话作为灵感。如果你不能找到一个精确的名字，这常常说明这个条目不应该存在。如果所有前面的事情都失败了并且你确认这个概念的存在，发明一个新名字。毕竟，“widget”、 “event”、“focus”和“buddy”这些名字就是这么来的。