What is a good reference documenting patterns of use of ".h" files in C?

Question

"C Interfaces and Implementations" shows some interesting usage patterns for data structures, but I am sure there are others out there.

http://www.amazon.com/Interfaces-Implementations-Techniques-Addison-Wesley-Professional/dp/0201498413

Answer 1

Makeheaders is an interesting approach: use a tool to generate the headers. Makeheaders is used in D. R. Hipp's cvstrac and fossil.

Answer 2

You might want to take a look at Large-Scale C++ Software Design by John Lakos.

Answer 3

Look at the Goddard Space Flight Center (NASA) C coding standard (at this URL). It has some good and interesting guidelines.

One specific guideline, which I've adopted for my own code, is that headers should be self-contained. That is, you should be able to write:

#include "header.h"

and the code should compile correctly, with any other necessary headers included, regardless of what has gone before. The simple way to ensure this is to include the header in the implementation source -- as the first header. If that compiles, the header is self-contained. If it doesn't compile, fix things so that it does. Of course, this also requires you to ensure that headers are idempotent - work the same regardless of how often they are included. There's a standard idiom for that, too:

#ifndef HEADER_H_INCLUDED
#define HEADER_H_INCLUDED
...operational body of header.h...
#endif /* HEADER_H_INCLUDED */

It is imperative, of course, to have the #define at the top of the file, not at the bottom. Otherwise, if a header included by this also includes header.h, then you end up with an infinite loop - not healthy. Even if you decide to go with a strategy of:

#ifndef HEADER_H_INCLUDED
#include "header.h"
#endif /* HEADER_H_INCLUDED */

in the code that include the header - a practice which is not recommended - it is important to include the guards in the header itself too.