API Design for C++

public:

Circle();

void Circle::SetRadius(float r)

The implementation of SetRadius() can then set major and minor radii of the underlying ellipse to the same value to enforce the properties of a circle.

float Circle::GetRadius() const

return GetMajorRadius();

void TestEllipse(Ellipse &e)

However, this poses a number of problems. The most obvious is that Circle will also inherit and expose the SetMajorRadius() and SetMinorRadius() methods of Ellipse. These could be used to break the self-consistency of our circle by letting users change one radius without also changing the other. You could deal with this by overriding the SetMajorRadius() and SetMinorRadius() methods so that each sets both major and minor radii. However, this also poses several issues. First, you must go back and declare Ellipse::SetMajorRadius() and Ellipse::SetMinorRadius() to be virtual so that you can override them in the Circle class. This in itself should alert you that you’re doing something wrong. Second, you have now created a non-orthogonal API: changing one property has the side effect of changing another property. Third, you have broken the Liskov Substitution Principle because you cannot replace uses of Ellipse with Circle without breaking behavior, as the following code demonstrates:

assert(e.GetMajorRadius() == 10.0 && e.GetMinorRadius() == 20.0);

e.SetMajorRadius(10.0);

e.SetMinorRadius(20.0);

TestEllipse(c); // fails!

The problem resolves to the fact that you have changed the behavior of functions inherited from the base class.

So if you shouldn’t use public inheritance to model a circle as a kind of ellipse, how should you represent it? There are two main ways that you can correctly build your Circle class upon the functionality of the Ellipse class: private inheritance and composition.

Tip

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

Private Inheritance

Private inheritance lets you inherit the functionality, but not the public interface, of another class. In essence, all public members of the base class become private members of the derived class. I refer to this as a “was-a” relationship in contrast to the “is-a” relationship of public inheritance. For example, you can redefine your Circle class to inherit privately from Ellipse as follows.

class Circle : private Ellipse

public:

Circle();

class Circle : private Ellipse

In this case, Circle does not expose any of the member functions of Ellipse, that is, there is no public Circle::SetMajorRadius() method. This solution therefore does not suffer from the same problems as the public inheritance approach discussed earlier. In fact, objects of type Circle cannot be passed to code that accepts an Ellipse because the Ellipse base type is not publicly accessible.

Note that if you do want to expose a public or protected method of Ellipse in Circle then you can do this as follows.

public:

Circle();

// expose public methods of Ellipse

using Ellipse::GetMajorRadius;

using Ellipse::GetMinorRadius;

Composition

Private inheritance is a quick way to fix an interface that violates the LSP if it already uses public inheritance. However, the preferred solution is to use composition. This simply means that instead of class S inheriting from T, S declares T as a private data member (“has-a”) or S declares a pointer or reference to T as a member variable (“holds-a”). For example,

private:

Ellipse mEllipse;

void Circle::SetRadius(float r)

Then the definition of the SetRadius() and GetRadius() methods might look like

mEllipse.SetMajorRadius(r);

mEllipse.SetMinorRadius(r);

float Circle::GetRadius() const

return mEllipse.GetMajorRadius();

IRenderer *RendererFactory::CreateRenderer(const std::string &type)

In this case, the interface for Ellipse is not exposed in the interface for Circle. However, Circle still builds upon the functionality of Ellipse by creating a private instance of Ellipse. Composition therefore provides the functional equivalent of private inheritance. However, there is wide agreement by object-oriented design experts that you should prefer composition over inheritance (Sutter and Alexandrescu, 2004).

Tip

Prefer composition to inheritance.

The main reason for this preference is that inheritance produces a more tightly coupled design. When a class inherits from another type—be it public, protected, or private inheritance—the subclass gains access to all public and protected members of the base class, whereas with composition, the class is only coupled to the public members of the other class. Furthermore, if you only hold a pointer to the other object, then your interface can use a forward declaration of the class rather than #include its full definition. This results in greater compile-time insulation and improves the time it takes to compile your code. Finally, you should not force an inheritance relationship when it is not appropriate. The preceding discussion told us that a circle should not be treated as an ellipse for purposes of type inheritance. Note that there may still be a good case for a general Shape type that all shapes, including Circle and Ellipse, inherit from. However, a Circle should not inherit from Ellipse because it actually exhibits different behavior.

4.6.5 The Open/Closed Principle

Bertrand Meyer introduced the Open/Closed Principle (OCP) to state the goal that a class should be open for extension but closed for modification (Meyer, 1997). Essentially this means that the behavior of a class can be modified without changing its source code. This is a particularly relevant principle for API design because it focuses on the creation of stable interfaces that can last for the long term.

The principal idea behind the OCP is that once a class has been completed and released to users, it should only be modified to fix bugs. However, new features or changed functionality should be implemented by creating a new class. This is often achieved by extending the original class, either through inheritance or composition, although, as covered later in this book, you can also provide a plugin system to allow users of your API to extend its basic functionality.

As an example of the OCP used to practical effect, the simple factory method presented in Chapter 3 is not closed to modification or open for extensibility. That’s because adding new types to the system requires changing the factory method implementation. As a reminder, here’s the code for that simple renderer factory method.

return new OpenGLRenderer();

if (type == "opengl")

if (type == "directx")

return new DirectXRenderer();

if (type == "mesa")

return new MesaRenderer();

return NULL;

• Call other functions in the same class.

In contrast, the extensible renderer factory that was presented later in Chapter 3 allows for the system to be extended without modifying the factory method. This is done by allowing clients to register new types with the system at run time. This second implementation therefore demonstrates the Open/Closed Principle: the original code does not need to be changed in order to extend its functionality.

However, when adhered to strictly, the OCP can be difficult to achieve in real-world software projects and even contradicts some of the principles of good API design that have been advanced here. The constraint to never change the source code of a class after it is released is often impractical in large-scale complex systems, and the stipulation that any changes in behavior should trigger the creation of new classes can cause the original clean and minimal design to be diluted and fractured. In these cases, the OCP may be considered more of a guiding heuristic rather than a hard-and-fast rule. Also, while a good API should be as extensible as possible, there is tension between the OCP and the specific advice in this book that you should declare member functions to be virtual in a judicious and restrained manner.

Nevertheless, if I restate the OCP to mean that the interface of a class should be closed to change rather than considering the precise implementation behind that interface to be immutable, then you have a principle that aligns reasonably well with the focus of this book. That is, maintenance of a stable interface gives you the flexibility to change the underlying implementation without unduly affecting your client’s code. Furthermore, the use of extensive regression testing can allow you to make internal code changes without impacting existing behavior that your users rely upon. Also, use of an appropriate plugin architecture (see Chapter 12) can provide your clients with a versatile point of extensibility.

Tip

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

4.6.6 The Law of Demeter

The Law of Demeter (LoD), also known as the Principle of Least Knowledge, is a guideline for producing loosely coupled designs. The rule was proposed by Ian Holland based on experiences developing the Demeter Project at Northeastern University in the late 1980s (Lieberherr and Holland, 1989). It states that each component should have only limited knowledge about other components, and even then only closely related components. This can be expressed more concisely as only talk to your immediate friends.

When applied to object-oriented design, the LoD means that a function can:

• Call functions on data members of the same class.

• Call functions on any parameters that it accepts.

• Call functions on any local objects that it creates.

• Call functions on a global object (but you should never have globals).

By corollary, you should never call a function on an object that you obtained via another function call. For example, you should avoid chaining function calls such as

void MyClass::MyFunction()

mObjectA.GetObjectB().DoAction();

void MyClass::MyFunction()

One way to avoid this practice involves refactoring object A so that it provides direct access to the functionality in object B, thus allowing you to do the following:

mObjectA.DoAction();

void MyClass::MyFunction(const ObjectB &objectB)

Alternatively, you could refactor the calling code so that it has an actual object B to invoke the required function directly. This can be done either by storing an instance or reference to object B in MyClass or by passing object B into the function that needs it, for example,

objectB.DoAction();

• Simple class names should be powerful, descriptive, and self-explanatory. Moreover, they should make sense in the problem domain being modeled and should be named after the thing they are modeling, for example, Customer, Bookmark, or Document. As already noted, class names tend to form the nouns of your system: the principal objects of your design.

The downside of this technique is that you introduce lots of thin wrapper methods into your classes, increase the parameter count of your functions, or increase the size of your objects. However, the benefit is that you end up with more loosely coupled classes where the dependencies on other objects are made explicit. This makes the code much easier to refactor or evolve in the future. In fact, the latter solution of explicitly passing an object into a function has clear parallels with the modern practice of dependency injection (discussed in Chapter 3). Also, another application of the LoD involves creating a single method in object A that aggregates calls to multiple methods of object B, which resonates well with the Façade design pattern.

Tip

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

4.6.7 Class Naming

While I have been largely concerned with the details of object-oriented design in these latest sections, once you have developed an appropriate collection of classes, an equally critical task is the development of expressive and consistent names for these classes. Accordingly, here are some guidelines for naming your classes.

• Joshua Bloch states that good names drive good designs. Therefore, a class should do one thing and do it well, and a class name should instantly convey its purpose (Bloch, 2008). If a class is difficult to name, that’s usually a sign that your design is lacking. Kent Beck offers the example that he originally used the generic compound name DrawingObject for an object in a graphical drawing system, but later refined this to the more expressive term Figure by referring to the field of typography (Beck, 2007).

• Sometimes it is necessary to use a compound name to convey greater specificity and precision, such as TextStyle, SelectionManager, or LevelEditor. However, if you are using any more than two or three words then this can indicate that your design is too confusing or complex.

• Interfaces (abstract base classes) tend to represent adjectives in your object model. They can therefore be named in this way, for example, Renderable, Clonable, or Observable. Alternatively, it’s common to prefix interface classes with the uppercase letter “I,” for example, IRenderer and IObserver.

• Avoid cryptic abbreviations. Good class names should be obvious and consistent. Don’t force your users to try and remember which names you’ve abbreviated and which you have not. I will revisit this point later when I discuss function naming.

• You should include some form of namespace for your top-level symbols, such as classes and free functions, so that your names do not clash with those in other APIs that your clients may be using. This can be done either via the C++ namespace keyword or through the use of a short prefix. For example, all OpenGL function calls start with “gl” and all Qt classes begin with “Q.”

4.7 Function Design

The lowest granularity of API design is how you represent individual function calls. While this may seem like an obvious exercise and not worth covering in much detail, there are actually many function-level issues that affect good API design. After all, function calls are the most commonly used part of an API: they are how your clients access the API’s behavior.

4.7.1 Function Design Options

There are many interface options you can control when designing a function call (Lakos, 1996). First of all, for free functions you should consider the following alternatives:

• Static versus non-static function.

• Pass arguments by value, reference, or pointer.

• Pass arguments as const or non-const.

• Use of optional arguments with default values.

• Return result by value, reference, or pointer.

• Return result as const or non-const.

• Operator or non-operator function.

• Use of exception specifications.

For member functions, you should consider all of these free function options as well as the following:

• Virtual versus non-virtual member function.

• Pure virtual versus non-pure virtual member function.

• Const versus non-const member function.

• Public, protected, or private member function.

• Use of the explicit keyword for non-default constructors.

In addition to these options that control the logical interface of a function, there are a couple of organizational attributes that you can specify for a function, such as

• Friend function versus non-friend function.

• Inline function versus non-inline function.

The proper application of these options can make a large impact on the quality of your API. For example, you should declare member functions as const wherever possible to advertise that they do not modify the object (see Chapter 6 on C++ usage for more details). Passing objects as const references can reduce the amount of memory copying that your API causes (see Chapter 7 on performance). Use of the explicit keyword can avoid unexpected side effects for non-default constructors (see Chapter 6). Also, inlining your functions can sometimes offer a performance advantage at the cost of exposing implementation details and breaking binary compatibility (see Chapters 7 and 8).

4.7.2 Function Naming

Function names tend to form the verbs of your system, describing actions to be performed or values to be returned. Here are some guidelines for naming your free and member functions.

• Functions used to set or return some value should fully describe that quantity using standard prefixes such as Get and Set. For example, a function that returns the zoom factor for a Web view might be called GetZoomFactor() or, less expressively, just ZoomFactor().

• Functions that answer yes or no queries should use an appropriate prefix to indicate this behavior, such as Is, Are, or Has, and should return a bool result, for example, IsEnabled(), ArePerpendicular(), or HasChildren(). As an alternative, the STL tends to drop the initial verb, as can be seen in functions such as empty() instead of IsEmpty(). However, while terser, this naming style is ambiguous because it could also be interpreted as an operation that empties the container (unless you’re astute enough to notice the const method decorator). The STL scheme therefore fails the qualities of discoverability and difficulty to misuse.

• Functions used to perform some action should be named with a strong verb, for example, Enable(), Print(), or Save(). If you are naming a free function, rather than a method of a class, then you should include the name of the object that the action will be applied to, for example, FileOpen(), FormatString(), MakeVector3d().

• Use positive concepts to name your functions rather than framing them in the negative. For example, use the name IsConnected() instead of IsUnconnected(). This can help to avoid user confusion when faced with double negatives like !IsUnconnected().

• Function names should describe everything that the routine does. For example, if a routine in an image processing library performs a sharpening filter on an image and saves it to disk, the method should be called something like SharpenAndSaveImage() instead of just SharpenImage(). If this makes your function names too long, then this may indicate that they are performing too many tasks and should be split up (McConnell, 2004).

• You should avoid abbreviations. Names should be self-explanatory and memorable, but the use of abbreviations can introduce confusing or obscure terminology. For example, the user has to remember if you are using GetCurrentValue(), GetCurrValue(), GetCurValue(), or GetCurVal(). Some software projects specify an explicit list of accepted abbreviations that must be conformed to, but in general it’s simply easier for your users if they don’t have to remember lists such as these.

• Functions should not begin with an underscore character (_). The C++ standard states that global symbols starting with an underscore are reserved for internal compiler use. The same is true for all symbols that begin with two underscores followed by a capital letter. While you can find legal combinations of leading underscore names that navigate these rules, it is generally best simply to avoid this practice in your function names (some developers use this convention to indicate a private member).

• Functions that form natural pairs should use the correct complementary terminology. For example, OpenWindow() should be paired with CloseWindow(), not DismissWindow(). The use of precise opposite terms makes it clearer to the user that one function performs the opposite function of another function (McConnell, 2004). The following list provides some common complementary terms.

Add/Remove	Begin/End	Create/Destroy
Enable/Disable	Insert/Delete	Lock/Unlock
Next/Previous	Open/Close	Push/Pop
Send/Receive	Show/Hide	Source/Target

4.7.3 Function Parameters

Use of good parameter names can also have a big impact on the discoverability of your API. For example, compare these two signatures for the standard C function strstr(), which searches for the first occurrence of a substring within another string:

char *strstr(const char *s1, const char *s2);

and

char *strstr(const char *haystack, const char *needle);

I think you’ll agree that the second signature gives a much better indication of how to use the function simply through the use of descriptive parameter names.

Another factor is to make sure that you use the right data type for your parameters. For example, when you have methods that perform linear algebra calculations, you should prefer using double-precision floats to avoid loss of precision errors that are inherent in single-precision operations. Similarly, you should never use a floating-point data type to represent monetary values because of the potential for rounding errors (Beck, 2002).

There is also a balance to be sought in terms of the number of parameters that you specify for each function. Too many parameters can make the call more difficult to understand and to maintain. It can also imply greater coupling and may suggest that it is time to refactor the function. Therefore, wherever possible you should try to minimize the number of parameters to your public functions. In this regard, we have the often-cited research from the field of cognitive science, which states that the number of items we can hold in our short-term working memory is seven plus or minus two (Miller, 1956). This may suggest that you should not exceed around five to seven parameters, as otherwise the user will find it difficult to remember all of the options. Indeed, Joshua Bloch suggests that five or more parameters are too many (Bloch, 2008).

Tip

Avoid long parameter lists.

For functions that accept many optional parameters, you may consider passing the arguments using a Plain Old Data (POD) struct or map instead. For example,

struct OpenWindowParams

std::string mClassName;

std::string mWindowName;

void OpenWindow(const OpenWindowParams &params);

This technique is also a good way to deal with argument lists that may change over the life of the API. A newer version of the API can simply add new fields to the end of the structure without changing the signature of the OpenWindow() function. You can also add a version field (set by the constructor) to allow binary compatible changes to the structure: the OpenWindow() function can then check the version field to determine what information is included in the structure. Other options include using a field that records the size of the structure in bytes or simply using a different structure.

Reducing Parameter Lists

All the way back in the 1980s, the Commodore Amiga platform provided an extensive set of stable and well-designed APIs to build applications that run under AmigaOS. The original routine to open a new screen on the Amiga takes a single argument: a structure containing all the necessary information to specify that screen.

struct Screen *OpenScreen(struct NewScreen *newscr);

The NewScreen structure looks like

struct NewScreen

WORD LeftEdge, TopEdge, Width, Height, Depth;

UBYTE DetailPen, BlockPen;

UWORD ViewModes, Type;

struct TextAttr *Font;

UBYTE *DefaultTitle;

struct Gadget *Gadgets;

struct BitMap *CustomBitMap;

struct Screen *OpenScreenTagList(struct NewScreen *newscr,

In Version 36 of the AmigaOS APIs, new functionality was added to this function. This was done by introducing the notion of tag lists, essentially an arbitrarily long list of keyword/value pairs. To support this new extensible scheme, a V36-only function was added to allow the explicit specification of these tag lists:

struct TagItem *taglist);

However, to maintain backwards compatibility, it was also possible to pass a new ExtNewScreen structure to the OpenScreen() function.

struct Screen *OpenScreen(struct ExtNewScreen *newscr);

This extended structure looks like

struct ExtNewScreen

WORD LeftEdge, TopEdge, Width, Height, Depth;

UBYTE DetailPen, BlockPen;

UWORD ViewModes, Type;

struct TextAttr *Font;

UBYTE *DefaultTitle;

struct Gadget *Gadgets;

struct BitMap *CustomBitMap;

struct TagItem *Extension;

timer.setSingleShot(true);

When passing this new structure to OpenScreen() you had to set the NS_EXTENDED bit of the Type field to indicate that the structure included an Extension field at the end. In this way, you could pass either the old or the new form to newer versions of AmigaOS, but older versions of amiga.lib would safely ignore new data.

Note that this is a plain C API, which cannot support function overloading, so the two versions of the OpenScreen() function were not specified in the same version of the API. Newer versions of the API would specify the ExtNewScreen signature, although code that tried to pass an older NewScreen structure would still compile fine under a C compiler (perhaps with a warning). In C++, this type mismatch would cause a compile error, but in that case you could simply provide two overloaded versions of OpenScreen().

Taking this one step further, you can hide all of the public member variables and only allow the values to be accessed via getter/setter functions. The Qt API refers to this as a property-based API. For example,

QTimer timer;

timer.setInterval(1000);

timer.start();

This lets you reduce the number of parameters required for functions; in this case, the start() function requires no parameters at all. The use of functions to set parameter values also offers the following benefits:

• Values can be specified in any order because function calls are order independent.

• The purpose of each value is more evident because you must use a named function to set the value, for example, setInterval().

• Optional parameters are supported by simply not calling the appropriate function.

• The constructor can define reasonable default values for all settings.

• Adding new parameters is backward compatible because no existing functions need to change signature. Only new functions are added.

Taking this even further, we could make each of the setter methods return a reference to its object instance (return *this;) so that you can chain a number of these methods together. This is called the Named Parameter Idiom (NPI). It offers the same benefits that I just enumerated while also letting your clients write less code. For instance, you could rewrite the QTimer example using the NPI as follows:

QTimer timer = QTimer().setInterval(1000).setSingleShot(true).start();

4.7.4 Error Handling

A large amount of the code that application developers write is purely there to handle error conditions. The actual amount of error handling code that is written will depend greatly on the particular application. However, it has been estimated that up to 90% of an application’s code is related to handling exceptional or error conditions (McConnell, 2004). This is therefore an important area of API design that will be used frequently by your clients. In fact, it is included in Ken Pugh’s Three Laws of Interfaces (Pugh, 2006):

1. An interface’s implementation shall do what its methods say it does.

2. An interface’s implementation shall do no harm.

3. If an interface’s implementation is unable to perform its responsibilities, it shall notify its caller.

Accordingly, the three main ways of dealing with error conditions in your API are

1. Returning error codes.

2. Throwing exceptions.

3. Aborting the program.

The last of these is an extreme course of action that should be avoided at all costs—and indeed it violates the third of Pugh’s three laws—although there are far too many examples of libraries out there that call abort() or exit(). As for the first two cases, different engineers have different proclivities toward each of these techniques. I will not take a side on the exceptions versus error code debate here, but rather I’ll attempt to present impartially the arguments and drawbacks for each option. Whichever technique you select for your API, the most important issues are that you use a consistent error reporting scheme and that it is well documented.

Tip

Use a consistent and well-documented error handling mechanism.

The error codes approach involves returning a numeric code to indicate the success or failure of a function. Normally this error code is returned as the direct result of a function. For example, many Win32 functions return errors using the HRESULT data type. This is a single 32-bit value that encodes the severity of the failure, the subsystem responsible for the error, and an actual error code. The C standard library also provides examples of non-orthogonal error reporting design, such as the functions read(), waitpid(), and ioctl() that set the value of the errno global variable as a side effect. OpenGL provides a similar error reporting mechanism via an error checking function called glGetError().

The use of error codes produces client code that looks like

if (obj1.Function() == ERROR)

if (obj2.Function() == ERROR)

if (obj3.Function() == ERROR)

catch (const std::exception &e)

As an alternative, you can use C++’s exception capabilities to signal a failure in your implementation code. This is done by throwing an object for your clients to catch in their code. For example, several of the Boost libraries throw exceptions to communicate error conditions to the client, such as the boost::iostreams and boost::program_options libraries. The use of exceptions in your API results in client code such as

int FindName(std::string *name);

The error codes technique provides a simple, explicit, and robust way to report errors for individual function calls. It’s also the only option if you’re developing an API that must be accessible from plain C programs. The main dilemma comes when you wish to return a result as well as an error code. The typical way to deal with this is to return the error code as the function result and use an out parameter to fill in the result value. For example,

…

std::string name;

if (FindName(&name) == OKAY)

std::cout << "Name: " << name << std::endl;

boost::tuple<int, std::string> FindName();

Dynamic scripting languages such as Python handle this more elegantly by making it easy to return multiple values as a tuple. This is still an option with C++, however. For example, you could use boost::tuple to return multiple results from your function (or the C++11 version, std::tuple), as the following example demonstrates:

…

boost::tuple<int, std::string> result = FindName();

if (result.get<0>() == OKAY)

std::cout << "Name: " << result.get<1>() << std::endl;