C++ API设计

Functional requirements specify how your API should behave.

Use cases describe the requirements for your API from the perspective of the user.

Use cases can be simple lists of short goal-oriented descriptions or can be more formal structured specifications that follow a prescribed template.

User stories are a way to capture minimal requirements from users within an agile development process.

API design involves developing a top-level architecture and a detailed class hierarchy.

Architecture design is constrained by a multitude of unique organizational, environmental, and operational factors.

Always design for change. Change is inevitable.

Identifying the key objects for an API is difficult. Try looking at the problem from different perspectives and keep iterating and refining your model.

Avoid cyclic dependencies between components of your API.

Describe the high-level architecture and design rationale for your API in the accompanying user documentation.

Focus on designing 20% of the classes that define 80% of your API’s functionality.

Avoid deep inheritance hierarchies.

Avoid multiple inheritance, except for interfaces and mixin classes.

The LSP states that it should always be possible to substitute a base class for a derived class without any change in behavior.

Prefer composition to inheritance.

Your API should be closed to incompatible changes in its interface, but open to extensibility of its functionality.

The Law of Demeter (LoD) states that you should only call functions in your own class or on immediately related objects.

1.返回错误码----一个数值，win32 API就是这样设计 2.抛异常 3.终止程序

Use a consistent and well-documented error handling mechanism.

Derive your own exceptions from std::exception.

Fail quickly and cleanly with accurate and thorough diagnostic details.

Use the pimpl idiom to keep implementation details out of your public header files.

When using the pimpl idiom use a private nested implementation class. Only use a public nested Impl class (or a public non-nested class) if other classes or free functions in the .cpp must access Impl members.

1. You can’t hide private virtual methods in the implementation class. These must appear in the public class so that any derived classes are able to override them. 2. You may need to add a pointer in the implementation class back to the public class so that the Impl class can call public methods. Although you could also pass the public class into the implementation class methods that need it.

Make your class uncopyable.----------可以使用boost的noncopyable，实现机制实际上就是，对于拷贝构造函数声明为私有就可以了。 Explicitly define the copy semantics. ----------If you do want your users to be able to copy your pimpledobjects, then you should declare and define your own copy constructor and assignment operator.These can then perform a deep copy of your object, that is, create a copy of the Impl object instead of just copying the pointer.

#include <string>
class AutoTimer
{
public:
explicit AutoTimer(const std::string &name);
AutoTimer();
private:
// Make this object be non-copyable
AutoTimer(const AutoTimer &);
const AutoTimer &operator ¼(const AutoTimer &);
class Impl;
Impl *mImpl;
};

Think about the copy semantics of your pimpl classes and consider using a smart pointer to manage initialization and destruction of the implementation pointer.

1.Information hiding. 2.Reduced coupling. 3.Faster compiles. 4.Greater binary compatibility. 5.Lazy Allocation.

The primary disadvantage of the pimpl idiom is that you must now allocate and free an additional implementation object for every object that is created. if you are concerned with the memory allocator performance, then you may consider using the “Fast Pimpl” idiom (Sutter, 1999) where you overload the new and delete operators for your Impl class to use a more efficient small-memory fixed-size allocator.

A Singleton is a more elegant way to maintain global state, but you should always question whether you need global state.

Declare the constructor, destructor, copy constructor, and assignment operator to be private (or protected) to enforce the Singleton property.

class Singleton
{

public:

static Singleton &GetInstance();


private:

Singleton();
Singleton();
Singleton(const Singleton &);
const Singleton &operator  = (const Singleton &);
};


static Singleton &obj  =  Singleton::GetInstance();

it would be dangerous to initialize our singleton using a non-local static variable.

Singleton &Singleton::GetInstance()
{
static Singleton instance;
return instance;
}

Singleton &Singleton::GetInstance()
{
Mutex mutex;
ScopedLock(&mutex); // unlocks mutex on function exit

static Singleton instance;
return instance;
}

Singleton &Singleton::GetInstance()
{
static Singleton *instance  = NULL;
if (! instance) // check #1
{
Mutex mutex;
ScopedLock(&mutex);
if (! instance) // check #2
{
instance  = new Singleton();
}
}
return *instance;
}

Creating a thread-safe Singleton in C++ is hard. Consider initializing it with a static constructor or an API initialization function.

Dependency injection is a technique where an object is passed into a class (injected) instead of having the class create and store the object itself.

class MyClass
{
MyClass() :
mDatabase(new Database("mydb", "localhost", "user", "pass"))
{}

private:
Database *mDatabase;
};

class MyClass
{
MyClass(Database *db) :
mDatabase(db)
{}
private:
Database *mDatabase;
};

Dependency injection makes it easier to test code that uses Singletons. Dependency injection can therefore be viewed as a way to avoid the proliferation of singletons by encouraging interfaces that accept the single instance as an input rather than requesting it internally via a GetInstance() method.

Consider using Monostate instead of Singleton if you don’t need lazy initialization of global data or if you want the singular nature of the class to be transparent.

There are several alternatives to the Singleton pattern, including dependency injection, the Monostate pattern, and use of a session context.

Use Factory Methods to provide more powerful class construction semantics and to hide subclass details.

Writing a wrapper interface that sits on top of another set of classes is a relatively common API design task. perhaps you are working with a large legacy code base and rather than rearchitecting all of that code you decide to design a new cleaner API that hides the underlying legacy code (Feathers, 2004). Or perhaps you have written a C++ API and need to expose a plain C interface for certain clients. Or perhaps you have a third-party library dependency that you want your clients to be able to access but you don’t want to expose that library directly to them.

The Proxy design pattern (Figure 3.3) provides a one-to-one forwarding interface to another class: calling FunctionA() in the proxy class will cause it to call FunctionA() in the original class.

A Proxy provides an interface that forwards function calls to another interface of the same form.

The Adapter design pattern (Figure 3.4) translates the interface for one class into a compatible but different interface.

The Fac¸ade design pattern (Figure 3.5) presents a simplified interface for a larger collection of classes. In effect, it defines a higher-level interface that makes the underlying subsystem easier to use.

An Observer lets you decouple components and avoid cyclic dependencies.

The MVC architectural pattern promotes the separation of core business logic, or the Model, from the user interface, or View. It also isolates the Controller logic that affects changes in the Model and updates the View.

Good APIs exhibit loose coupling and high cohesion.

class MyObject; // only need to know the name of MyObject
class MyObjectHolder
{
public:
MyObjectHolder();
void SetObject(MyObject *obj);
MyObject *GetObject() const;
private:
MyObject *mObj;
};

In this case, if the associated .cpp file simply stores and returns the MyObject pointer, and restricts any interaction with it to pointer comparisons, then it does not need to #include “MyObject.h” either. In that case, the MyObjectHolder class can be decoupled from the physical implementation of MyObject.

Use a forward declaration for a class unless you actually need to #include its full definition.

whenever you have a choice, you should prefer declaring a function as a non-member non-friend function rather than as a member function 。Doing so improves encapsulation and also reduces the degree of coupling of those functions to the class.

Prefer using non-member non-friend functions instead of member functions to reduce coupling.

// myobject.h
class MyObject
{
public:
void PrintName() const;
std::string GetName() const;
. . .
protected:
. . .
private:
std::string mName;
. . .
};

// myobject.h
class MyObject
{
public:
std::string GetName() const;
. . .
protected:
. . .
private:
std::string mName;
. . .
};
void PrintName(const MyObject &obj);

Data redundancy can sometimes be justified to reduce coupling between classes.

Manager classes can reduce coupling by encapsulating several lower-level classes.

reduce coupling within an API relates to the problem of notifying other classes when some event occurs.

your API should present the basic functionality via an easy-to-use interface while reserving advanced functionality for a separate layer

Add convenience APIs as separate modules or libraries that sit on top of your minimal core API.

Avoiding the use of abbreviations can also play a factor in discoverability

A good API, in addition to being easy to use, should also be difficult to misuse.

Prefer enums to booleans to improve code readability.

Avoid functions with multiple parameters of the same type.

Use consistent function naming and parameter ordering.

An orthogonal API means that functions do not have side effects.

1. Reduce redundancy. Ensure that the same information is not represented in more than one way.There should be a single authoritative source for each piece of knowledge. 2. Increase independence. Ensure that there is no overlapping of meaning in the concepts that are exposed. Any overlapping concepts should be decomposed into their basal components.

Null dereferencing: trying to use -> or * operators on a NULL pointer. Double freeing: calling delete or free() on a block of memory twice. • Accessing invalid memory: trying to use -> or * operators on a pointer that has not been allocated yet or that has been freed already. • Mixing Allocators: using delete to free memory that was allocated with malloc() or using free() to return memory allocated with new. • Incorrect array deallocation: using the delete operator instead of delete [] to free an array. • Memory leaks: not freeing a block of memory when you are finished with it.

1. Shared pointers. These are reference-counted pointers where the reference count can be incremented by one when a piece of code wants to hold onto the pointer and decremented by one when it is finished using the pointer. When the reference count reaches zero, the object pointed to by the pointer is automatically freed. This kind of pointer can help avoid the problems of accessing freed memory by ensuring that the pointer remains valid for the period that you wish to use it. 2. Weak pointers. A weak pointer contains a pointer to an object, normally a shared pointer, but does not contribute to the reference count for that object. If you have a shared pointer and a weak pointer referencing the same object, and the shared pointer is destroyed, the weak pointer immediately becomes NULL. In this way, weak pointers can detect whether the object being pointed to has expired: if the reference count for the object it is pointing to is zero. This helps avoid the dangling pointer problem where you can have a pointer that is referencing freed memory. 3. Scoped pointers. These pointers support ownership of single objects and automatically deallocate their objects when the pointer goes out of scope. They are sometimes also called auto pointers. Scoped pointers are defined as owning a single object and as such cannot be copied.

Return a dynamically allocated object using a smart pointer if the client is responsible for deallocating it.

Think of resource allocation and deallocation as object construction and destruction.

Never put platform-specific #if or #ifdef statements into your public APIs. It exposes implementation details and makes your API appear different on different platforms.

class MobilePhone
{
public:
bool StartCall(const std::string &number);
bool EndCall();
#if defined TARGET_OS_IPHONE
bool GetGPSLocation(double &lat, double &lon);
#endif
};

class MobilePhone
{
public:
bool StartCall(const std::string &number);
bool EndCall();
bool HasGPS() const;
bool GetGPSLocation(double &lat, double &lon);
};

bool MobilePhone::HasGPS() const
{
#if defined TARGET_OS_IPHONE
return true;
#else
return false;
#endif
}