Book review: API design for C++

I just finished the book “API design for C++” by Martin Reddy and wrote this review while reading.

I was mainly interested in the C++ part of the book, meaning how to design an API while considering the peculiarities of C++. As an experienced C++ programmer I wanted to know more about topics such as:

  • Application binary interface (ABI) and how to achieve binary compatibility
  • How to design an API that is binary compatible or compiler independent
  • Issues with memory allocations across dynamic libraries
  • Issues with exceptions across libraries
  • Trade offs are regarding recompilation, stability and compiler dependencies
  • Dealing with changes in APIs and how to implement versioning for an API

Contents

The book starts off with some introduction and then explains what kind of features a good API should have (such as Robust, platform independent,, …). No big surprises here.

After that the book discusses some design patterns that play a role in API design (factory, observer, …). Mostly standard GoF patterns with the exceptions of the pimpl idiom which is specific to C++. In this section it becomes clear that the books is a bit outdated regarding the C++ standard. Multiple suggestions by the book are not state of the art anymore. Not a big issue but an updated version would be nice. At least the book already uses smart pointers.

I bought the book more or less for the next two chapters: “Styles” and “C++ usage”. The “Styles” chapter discusses different kinds of APIs such as flat C API, object oriented C++ design or template based design. The chapter is only 22 pages long, which I found quite disappointing as I consider this chapter the heart of the book. Consequently the book hardly scratches the surface. I would have liked the book to cover topics such as how to provide a C API as a thin wrapper but using C++ internally. Or how to deal with classes from the standard library when potentially using different compilers. The “C++ usage” chapter is only marginally connected to API design. It is more a best practice for C++. Most of the content is ok, but some of it is outdated and would expect that most readers already know most of it.

The “Performance” chapter is again more a best practice and only slightly related to C++ API design.

The next chapter was of interest for me: Versioning. The book starts a the very beginning and explains what version numbers are and what they me. I find this a bit too basic for such a book as I would expect most readers to be experienced developers. It also explains the basic ideas how to use version numbers in an API but does not offer much insight. I would have liked to see an example of how to write an API that is backward compatible. Mainly how to do it without checking the version number in dozens of places and creating a big mess. 

The chapters about Documentation and Testing are alright. They don’t offer many surprises and if you ever read a book about these topics you won’t learn much new from here.

The two last chapters about “Scripting” and “Extensiblity” are more interesting again. In “Scripting” to book explains how to use an C++ API with Python or Ruby. This is something that interests me a lot, but the chapter is finished as soon as it gets interesting. The same goes for “Extensibility”: It is just not detailed enough.

Conclusion

The book is well written and quite easy to read. The concepts are well explained and the code examples are helpful. The book is well structures with relatively short chapters that are easy to digest. Content wise there is a chapter for all major aspects of an API, but most of the time it does not go deep enough for me.

This puts the book into a somewhat weird spot: It is not detailed enough to write real C++ APIs as it does not go deep enough into topics such as ABI. On the other hand the book offers some good advice for beginners, but if you are a beginner then it is problematic that the book is not up to date with the newest C++ standard. Therefore I cannot really recommend the book: For experienced developers there is not much new to learn as the book does not go into the nitty gritty details. For beginners the book is too outdated.

2 out of 5 stars from me.

Leave a Reply

Your email address will not be published. Required fields are marked *