Why not #inlude #include into #include?

I have an empirical rule of thumb, which I bring to all my C++ projects:

Do not #include other #includes in header files.
The only thee excuses are:

Inheritance: #include a base class to inherit from it.

Composition: #include a class to use it as a value member object.

Standard types: #include STL and standard headers for standard types used in class declaration.

In all other cases use forward declarations.

It sounds straightforward, even trivial. But somehow I find myself explaining it again and again to C++ programmers, even to quite experienced ones.

So, why not include extra #includes in header files? Here is my "short answer":

Each include introduces a dependency. Extra unnecessary includes introduce extra ways many unnecessary dependencies. The application soon snowballs to a monolithic blob of well pressed spaghetti code, where everything depends on everything.

The order of .h files suddenly matters: sometimes it magically works because of the hidden includes. But this white magic becomes black magic. Someone removes an #include because noone seems to use it. This innocent change breaks things 5 header files away, it doesn't complile any more. So scared programmers don’t dare to change the order of #includes.

Any touch in any include file results in rebuilding the whole application. Nowadays the compiling time doesn't concern me (if it concerns you, check out Xoreax IncrediBuild). But the fact that the whole system has been recompiled concerns QA folks: the files now are not binary equal so all bets are off and they got to retest the whole application!



Code reuse, refactoring, and unit testing become almost impossible. Every class drags behind the entire code base.



For long answer, I refer you to "Large Scale C++ Software Design" by John Lakos.

The "rule of thumb above is a simple and powerful empirics to keep C++ code dependencies under control.

This is the way I teach C++ programmers not to #include #include files into #include files. What do you think? Am I doing something right? Leave your comments, please help me do better.