What is best practice for C++ Public API?

Question

What is best practice for C++ Public API?

I am working on a C++ project that has multiple namespaces, each with multiple objects. Some objects have the same names, but are in different namespaces. Currently, each object has its own .cpp file and .h file. I am not sure how to word this... Would it be appropriate to create a second .h file to expose only the public API? Should their be a .h file per namespace or per object or some other scope? What might be a best practice for creating Public APIs for C++ libraries?

Thanks For Any Help, Chenz

Answer 1

I'd say it's best decided by you, and the type of 'library' this is.

Is your API provides one "Action"? or handles only one abstract "Data type"? examples for this would be zlib and libpng. Both have only one header that gives everything that is needed to perform what the libraries are for.

If your library is a collection of unrelated (or even related) classes that do, or not, the same goal, then provide each subset with it's own header. Major example for this will be boost.

Answer 2

It is sometimes convenient to have a single class in every .cpp and .h pair of files and to have the namespace hierarchy as the directory hierarchy.
For instance if you have this class:

namespace stuff {
  namespace important {
    class SecretPassword 
    {
       ...
    };
  }
}

then it will be in two files:

/stuff/important/SecretPassword.cpp
/stuff/important/SecretPassword.h

another possible layout might be:

/src/stuff/important/SecretPassword.cpp
/include/stuff/important/SecretPassword.h

Answer 3

Great response LiraNuna.

Are you providing an API to an application or a library?

An application API will generally only provide methods that either query the state of an application or attempt to alter that state. In this case you'd generally have separate interface declarations in a separate header file. Your objects would then implement this interface to handle API requests.

A library will generally expose objects that can be re-used. In this case, generally speaking, your API is simply the public methods in the header file.

Answer 4

G'day,

One suggestion is to take a look at the C++ idiom of Handle-Body, sometimes known as Cheshire Cat. Here's James Coplien's original paper containing the idiom.

This is a well known method for decoupling public API's from implementations.

HTH

Answer 5

Here is what I'm used to do:

"Some objects have the same names, but are in different namespaces"

That's why namespaces exist.

"Would it be appropriate to create a second .h file to expose only the public API? "

You always should expose only the public API. But what means to expose public API? If it would be only to headers then, since public API relies on private API, the private API would be included by public API anyway. To expose a public API mark public functions/classes with a macro (which in case of Windows exports public functions to the symbol table; and probably it will be soon adopted by Unix systems). So you should define a macro like MYLIB_API or MYLIB_DECLSPEC, just check some existing libraries and MS declspec documentation. It is sufficient, usually non-public API will be kept in subdirectories so it doesn't attend library's user.

"Should their be a .h file per namespace or per object or some other scope?"

I prefer Java-style, one public class per header. I found that libs written in this way are far more clean and readable than those which are mixing file and structure names. But there are cases when I brake this rule, especially when it comes to templates. In such cases I give #warning message to not include header directly and carefully explain in comments what is going on.

Answer 6

I agree with what doc said - one class per file. 99.9% of the time!

Also, consider what filenames to use. It's generally a bad idea to have multiple headers of the same name in different directories, even though the classes they contain may well be in different namespaces.

Especially if this is a public API, you probably cannot control what include paths are defined by the user of your library, so a build may find the wrong one. Tweaking the order of include paths would definitely not be a solution I'd recommend!

We use a naming convention of Namespace-Class.h to explicitly identify classes in files.