A standard header is one of the 15 defined by ANSI C, such as stdio.h, math.h, and string.h. ANSI requires you to include standard headers using the notation #include <header.h>. Do so even if #include "header.h" appears to work for them. A standard header is stored in some special place such that it can be accessed from all places in which a source file can be compiled.

A system header is one supplied by the compiler vendor that can be used to interface to and/or exploit the host hardware and/or operating system. Examples on MS-DOS systems include bios.h and dos.h; on VAX/VMS, headers rms.h, rab.h, and fab.h are used to access the RMS file system; and on UNIX, the special set sys\*.h is provided. An implementer can provide as many system headers as he needs. VAX C, for example, comes with about 200. Since system headers are useful to all applications, they are typically stored in the same place as standard headers.

A library header is one provided with a third-party library such as a windows, graphics, or statistical package. Again, a product may include many headers and you may use a number of different libraries in the same application. Library headers are also universally shareable and will likely reside with standard and system headers.

An application header is one you design for a particular application and as such, it should be located in a place separate from headers in the other three categories. It is possible, however, that over the course of designing an application, you build a header that is useful beyond the life of the current system. This header then, should really be treated as a miscellaneous library header. If each programmer on the project develops his own private miscellaneous headers naming conflicts can easily arise, so you must ensure that private headers are not used.

During testing stages of a project, it can be very tempting to provide a quick (and often dirty) fix to a given problem by simply changing a header and recompiling the offending source module. However, this can cause other nasty side-effects later on when the system as a whole is rebuilt. Also, you must never, never, ever even think of changing a standard, system, or library header; these are sacred. For example, you might discover you need macros called TRUE and FALSE in several modules and since stdio.h is included in all of them, why not simply add definitions for these macros to that header? Afterall, it can't hurt any existing uses of these headers, can it? Apart from reflecting bad style when you next (re)install the compiler, these changes are lost. One solution to this is to make all headers, including application headers that have been moved to production, read-only. That way, if you should ever try to change or overwrite them you are reminded of the seriousness of such an action.

The convention of naming headers with a .h suffix is exactly that, a convention and need not be followed by user-written headers. Certainly, it's a useful default convention if you have no good reason to do otherwise.

If you wish to port code, keep in mind that the length of significance, case distinction, and format of filename (assuming a header is a file), are all implementation-defined.

It is generally considered bad style to specify device and or directory information in a header name. Considering that almost all compilers provide compile-time options and/or environment variables to specify an include search path, I see no reason to unduly reduce your flexibility options.

My rule of thumb is to put all related stuff together in one header. However, if that makes for a very large header and the contents can easily be broken into logical subsets, then I prefer each subset be in its own header. It's useful to give such headers names with the same prefix so you can easily determine they are related. The only difference here is whether the preprocessor has to process one big header instead of just those parts it needs. Don't get too hung up on worrying how much work the preprocessor has to do unnecessarily since that's what CPU cycles are for. In fact, in the extreme case where you put each declaration in its own header, the preprocessor won't need to do any extra work, except for opening and closing all those headers.

It's quite likely that, while most things will fit neatly into related groups each in a header, some miscellaneous bits will be left over. About the only way to handle these reasonably is a miscellaneous header. ANSI C has one of these, called stddef.h. Whatever organization you chose, everything that can be shared should be shared. That is, you should make sure that all macros, function prototypes, etc., are part of some header and not hard-coded in source files directly.

Each header should be self-contained. If one header refers to something in another header, the first should directly include the second. Forcing the programmer to know and remember the order in which related headers need be included is burdensome and unnecessary.

/* header local.h */
#ifndef LOCAL_H
#define LOCAL_H
...
#endif

Since the standard headers can also be included multiple times and some of them contain typedefs and structure templates, these too must be protected. Check those provided with your compiler to see if they indeed are protected. The only difference between your wrapper and that used by the standard headers is that you must not begin your private macro name with an underscore while they must, since that's the implementer's namespace.

You also have the ANSI invention of #include macro where macro must expand to a header name of the form <...> or "...". You also can use the stringize and token pasting preprocessor operators # and ## respectively, to construct a macro that is to expand to a header name.

I have also found that it is a good idea to remove as many preprocessing directives as possible from source modules into headers. In particular, I find conditional compilation directives in source code to be most distracting, especially when there are more that two compilation paths. The aim is to isolate such dependencies into headers so you can forget about them and get on with the business of implementing or maintaining the application. An example of this strategy follows:

#if TARGET == 1
  fp = fopen("DBAO:[direct]master.date", "r");
#else
  fp = fopen("A:\direct\master.date", "r");
#endif

Over the years I have found it a useful idea to include a header called something like debug.h into every source file I write when working on a non-trivial project. If the header is empty, that's fine. However, it makes it very easy to add or change that header's contents and recompile all or part of the system for testing. Since you have one header included everywhere, it is trivially easy to make powerful changes and to experiment. And the cost of having this flexibility is practically nothing, if you cater for it at the beginning.

Let's look at just what can and cannot be split across multiple source modules, and therefore across multiple headers. A source module must contain complete tokens. That is, a source token cannot be split across two files. Specifically, the notation of backslash/new-line continuation cannot be used in the last line of a source file. Likewise, a comment cannot span two files.

With string literal concatenation now supported by ANSI, you could have a string in one file concatenated with a string in another, but that would require the strings to be outside a macro definition and I have already said that's very bad style. You could also split a structure template definition across multiple files, but I see no benefit.

One thing not immediately obvious in ANSI C is that each matching set of #if/endif and corresponding #elif and #else directives must be contained within the same source file. That is, the #if and matching #endif directives must be in the same source file.