Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free.

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

I'm looking for a good resource for learning about good API design for C++ libraries, looking at shared objects/dlls etc. There are many resources on writing nice APIs, nice classes, templates and so on at source level, but barely anything about putting things together in shared libs and executables. Books like Large-Scale C++ Software Design by John Lakos are interesting but massively outdated.

What I'm looking for is advice i.e. on handling templates. With templates in my API I often end up with library code in my executable (or other library) so if I fix a bug in there I can't simply roll out the new library but have to recompile and redistribute all clients of that code. (and yes, I know some solutions like trying to instantiate at least the most common versions inside the library etc.)

I'm also looking for other caveats and things to mind for keeping binary compatibility while working on C++ libraries.

Is there a good website or book on such things?

share|improve this question
I handled it this way: -- i.e. while there are templates inside the lib, none of it is in the api... – tp1 Sep 2 '12 at 14:36
std::unique_ptr is pretty new stuff. What exactly did you think was more suitable about your proposed API? The way in which you had to manually manage all the resources, virtually guaranteeing leaks and double deletes, for example? Or the way in which many of your types had one or two letter names, making divining their purpose impossible? – DeadMG Sep 2 '12 at 16:09
@tp1: But you didn't take any care to see that I did handle them. You just said "HANDLE THEM" without doing anything about it. I didn't handle them and now what? Instead of using an RAII class which does not permit such mistakes. If you had used unique_ptr it would not be possible to write code like that. – DeadMG Sep 2 '12 at 16:23
@tp1: I noticed that the Env can be destroyed. That's pretty much it. There doesn't appear to be any functionality to manage objects, at all. If I wanted to manage memory more fine grained than "Everything I ever created" or "Nothing", it would appear that I'm screwed. – DeadMG Sep 2 '12 at 16:33
Please take any extended conversation to Programmers Chat. Can any useful information be incorporated in the question or an answer? – ChrisF Sep 2 '12 at 18:19
up vote 6 down vote accepted

There is in-fact a book that is precisely what you seek. It is call, appropriately enough, API Design for C++.The book's website has source code from the book and Errata as well.

share|improve this answer
Definite +1 for the book! I came to suggest this but turns out you beat me to it. – zxcdw Sep 2 '12 at 15:48
+1: I am finishing reading this book and it is a great resource. Highly recommended. – Korchkidu Jul 11 '13 at 17:19

This is pretty much impossible. The simple fact is that sometimes, you need the compiler to do a job, and you can't just magic that necessity away. There is no function that can make std::vector not a header-only library. The compiler can make many magics work, but you can't have them without invoking it, and that's a fact of life.

Here's what you can do: don't use templates where you don't need them. Here's what you can't do: anything else.

The simple fact is that recompiling with the new version really isn't that big of a burden compared to the advantages of performance, safety, and functionality you can get with statically typed libraries.

share|improve this answer
I mentioned that as an example to think about. what I'm looking for is guidance on other similar issues which I should prepare for, and best practices to handle those. – johannes Sep 2 '12 at 17:16
Well, if all new versions breaking ABI-compatibility are put into a new inline-namespace, what does it matter whether it's a header-only library or not? – Deduplicator Oct 15 '15 at 0:56

Your Answer


By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.