Question

I need to create an API that will allow my customer’s developers to use a proprietary C module that will be released as a library (think .lib or .so — not source).

I’d like to make the header as developer-friendly as possible (so I won’t need to be), following best practices and providing comments with descriptions, examples, caveats, etc.

What else should I consider from business, technical, and plain common-sense perspectives?

Answer 1

The header file itself should be clean and tidy and probably close to minimal. It should point to where the documentation can be found. It probably shouldn’t include complete examples (notwithstanding some of my own headers that do that). It should include basic information about the copyright and licence and author details. It should only contain stuff that end users need – nothing that only the developers need. It should be self-contained; it should include any other headers necessary to make it work (so the user can write ‘#include 'your-header.h'‘ and the code will compile cleanly, even if that’s the first or only header they include).

Added: The header should include some basic version information too (file revision number and modification date, and/or the product release version number and release date). This helps people looking at two releases of the software — and successful software is released more than once.

Added: Adam asked me to expand on ‘and nothing that only the developers need’. That means, for example, that even though the internal functions may use some structure type, if none of the external interfaces uses that structure type, then the public header should not contain a definition of that structure type. It should be in a private header that is not distributed (or is only distributed with the complete source). It should not be polluting the public header. It is tempting to say ‘but it is only a little bit of wasted space’, and it is accurate, but if everyone wastes a little space and time, then the total waste can become expensive.

The key point about the public header is that it should contain everything that the user of the library (set of functions) needs, and nothing that they do not need.