API Design for C++ [Paperback]

A good book, but I don't think an experienced C++ programmer would find anything too surprising in it. It IS a very good tutorial for newer programmers, or someone coming from Java API design. The author does a nice job of explaining a lot of what has been discussed in Meyers' and Sutter's book; none of the lengthy set up and quizzing, he just explains it and shows the reader why it is important. He concisely explains things like Liskov, Open-Closed, etc., the PIMPL idiom, and creation patterns, and gives some good advice on how to version your API, and control development in a source control system. It's basically a pretty complete look at the whole process of writing an API.

First, the summary: This is an outstanding book which covers a very large range of topics very effectively. Don't be fooled by the title - even though APIs are covered very thoroughly, the book contains a great deal of wisdom beyond the API (at least by my definition of "API") - it discusses the design and implementation of well-encapsulated software components, performance, design patterns, effective use of the C++ programming language, and much more. Important topics that are often overlooked by other books, such as documentation, testing, versioning and scripting, are also covered. The book is extremely well written, and the typesetting and layout of the book is very well done. The book never loses sight of the motivation for a solid API - the winners are your clients and your business.

Usually when I think of an API, I think of the interface to a library / component. You know, function prototypes, class documentation, maybe some man pages or background documentation. All of that material is covered in great depth, but what the book is really about is *everything* that goes into designing and implementing software components / libraries properly. When writing a library, only the API is exposed to the user, and this is where a lot of the hard work is. Deciding what needs to be exposed, and how it should be exposed, is often not easy. As the author states, you can always change the underlying implementation, but you really need to think through the API before unleashing your API on the world. That's why it's so important to "get it right the first time" - changes afterwards can be tremendously costly. This book will help you get it right the first time.

In my work, I spend a lot of my time re-factoring software components & their interfaces to make them less fragile, more re-usable, more testable, and easier to use correctly. This book taught me a couple new tricks that will help me do that better. And no doubt, in the rare case where I actually get to create a library/API from scratch, I'll also do a better job going forward. (If enough people buy this book, I might have to start looking a lot harder for clients!)

You can browse the Table of Contents yourself to see the range of topics covered - it's broad. There isn't a weak chapter in the book. I don't think I found a single technical mistake or inaccuracy in the book. The code examples are small, concise, illustrative and clean. The writing is stellar. Rather than just dictate a bunch of rules, the author provides the rationale for the suggestions. The author also cites references and sources for further reading throughout the book.

Another nice aspect of the book is how the author's real-world experience on very large & complex development projects shines through when discussing certain topics. The information in the book has been obtained by lots of hard work, and seeing what works and what doesn't.

I liked the book's treatment of C++-specific features that can contribute to writing a good API. Language features such as templates, namespaces, inheritance and const correctness are discussed very effectively. Even features in the upcoming C++0x (or whatever it's called these days) standard, at least those that can help improve your API, are covered too.

The book reads very well. Anyone who's opened Stroustrup's "The C++ Programming Language" knows that poor typesetting can have a large negative impact of the book's readability. This book is just the opposite. The fonts are clean, code is well-formatted, tips are called out in highlight boxes, and diagrams are clear and uncluttered. Boldface, bullet items and numbered lists are used effectively to guide the reader's eyes throughout the reading. To me, this is very important - I've come across several books that appeared to be nothing more than Word documents printed out & bound. The content is well-organized and the topics flow well. It never feels like something was just "shoehorned" into a chapter because there was no better place to put it.

The bottom line: if you're writing C++ (or even C) code for other people to use, you need this book.

My job is maintaining and expanding a large cross-platform desktop application which was originally written in 1986 by highly intelligent but inexperienced developers, and whose code is also used for browser plugins. If only I could have sent back in time this book! My life would be easy. I wouldn't have spent years of my life getting the basics of maintainability in place, simple things like using accessor methods, but also more subtle concepts like the importance of decoupling objects and techniques to decouple. This book is nominally about putting together APIs, but along the way it encourages and demands the programmer choose the most maintainable, robust and professionally rigorous techniques in order to reach the goal of an easy to use, hard to screw up, predictable and stable external API.

I want to emphasize the importance of such software traits as modularity, implementation hiding, and decoupling in any large project, in my own case I see years of what the book calls "software debt" accumulating and coming due with a vengeance. If robust techniques are not mandated and enforced every day of the release cycle eventually the codebase will become daunting to modify or fix. Such techniques given in the book as factory methods, the observer/broadcaster pattern, and such off the shelf technologies like Boost to ease implementation of these techniques are just what you have to use in order to keep sane and keep your cash cow alive.

Not that I don't have quibbles with certain techniques. I'm no fan of the PIMPL pattern and prefer to solve the same problem of implementation hiding with virtual base class interfaces and class factory methods. But then again, I don't write libraries, I write applications and plugins, so I will defer to Mr. Reddy's judgement for when it comes to libraries.

There is a very clear chapter on various topics in using the C++ language such as best practices for using templates. Now, I avoid templates (other than using STL and boost) like the plague; I don't like the syntax, and I don't come across many interesting cases where I need to share methods amongst different data types, so yes, I'm not a generic style programmer, but I will admit that the template techniques as the author puts them forward seem clear and useful enough, including the Curiously Recurring Template Pattern which he tucks into the last pages of the last chapter.

The book has interesting chapters on such topics as adding scripting interfaces in either Python or Ruby. Once it's all lain out, it almost seems simple to create one, especially if you are using pre-existing frameworks like Boost or Swig to do the heavy lifting. There is an Appendix devoted to library packaging technologies which would have been useful to know back in the day.

So my recommendation is that if you are a C++ programmer and you want to improve yourself, to learn from a master, and be able to call yourself a professional coder, then you need to read this book. It is the best technical book I've read in years and I've recommended it to everyone on my team.