C++ class header files organization

What are the C++ coding and file organization guidelines you suggest for people who have to deal with lots of interdependent classes spread over several source and header files?

I have this situation in my project and solving class definition related errors crossing over several header files has become quite a headache.

Some general guidelines:

• Pair up your interfaces with implementations. If you have foo.cxx, everything defined in there had better be declared in foo.h.
• Ensure that every header file #includes all other necessary headers or forward-declarations necessary for independent compilation.
• Resist the temptation to create an "everything" header. They're always trouble down the road.
• Put a set of related (and interdependent) functionality into a single file. Java and other environments encourage one-class-per-file. With C++, you often want one set of classes per file. It depends on the structure of your code.
• Prefer forward declaration over #includes whenever possible. This allows you to break the cyclic header dependencies. Essentially, for cyclical dependencies across separate files, you want a file-dependency graph that looks something like this:
  • A.cxx requires A.h and B.h
  • B.cxx requires A.h and B.h
  • A.h requires B.h
  • B.h is independent (and forward-declares classes defined in A.h)

If your code is intended to be a library consumed by other developers, there are some additional steps that are important to take:

• If necessary, use the concept of "private headers". That is, header files that are required by several source files, but never required by the public interface. This could be a file with common inline functions, macros, or internal constants.
• Separate your public interface from your private implementation at the filesystem level. I tend to use include/ and src/ subdirectories in my C or C++ projects, where include/ has all of my public headers, and src/ has all of my sources. and private headers.

I'd recommend finding a copy of John Lakos' book Large-Scale C++ Software Design. It's a pretty hefty book, but if you just skim through some of his discussions on physical architecture, you'll learn a lot.

Check out the C and C++ coding standards at the NASA Goddard Space Flight Center. The one rule that I specially noted in the C standard and have adopted in my own code is the one that enforces the 'standalone' nature of header files. In the implementation file xxx.cpp for the header xxx.h, ensure that xxx.h is the first header included. If the header is not self-contained at any time, then compilation will fail. It is a beautifully simple and effective rule.

The only time it fails you is if you port between machines, and the xxx.h header includes, say, <pqr.h>, but <pqr.h> requires facilities that happen to be made available by a header <abc.h> on the original platform (so <pqr.h> includes <abc.h>), but the facilities are not made available by <abc.h> on the other platform (they are in def.h instead, but <pqr.h> does not include <def.h>). This isn't a fault of the rule, and the problem is more easily diagnosed and fixed if you follow the rule.

Check the header file section in Google style guide

Tom's answer is an excellent one!

Only thing I'd add is to never have "using declarations" in header files. They should only be allowed in implementation files, e.g. foo.cpp.

The logic for this is well described in the excellent book "Accelerated C++" (Amazon link - sanitised for script kiddie link nazis)

One more point in addition to the others here:

> Don't include any private definitions > in an include file. E.g. any > definition that is only used in > xxx.cpp should be in xxx.cpp, not > xxx.h.

Seems obvious, but I see it frequently.

I'd like to add one very good practice (both in C and C++) which is often forsaken :

foo.c

#include "foo.h" // always the first directive

Any other needed headers should follow, then code. The point is that you almost always need that header for this compilation unit anyway and including it as a first directive warrants the header remains self-sufficient (if it is not, there will be errors). This is especially true for public headers.

If at any point you need to put something before this header inclusion (except comments of course), then it is likely you're doing something wrong. Unless you really know what you are doing... which leads to another more crucial rule => comment your hacks !