Avoid including .h files in .h files.

[alecjohnson]

Currently many header files include system header files or include other header files unnecessarily.

The number of .h files included in a .h file should be minimized, for two reasons:

1. The practice of including .h files in .h files can dramatically increase the time required to compile. In particular, including the .h files from the iostream libraries results in typically 20,000 lines of declarations that must be processed by the compiler for every .cpp file for which they get included. I reduced compile time of DOGPACK from 45 seconds to 15 seconds by eliminating such inclusion of the iostream library.
2. The practice of including .h files in .h files creates potential code dependencies, which makes it much harder to sort out what really depends on what, both for the programmer and for code-analyzing software. Related to this, cmake analyzes the .h file include graph and generate a makefile that incorporates all dependencies so that you never have to type "make clean". Including .h files in .h files can greatly increase the number of files that cmake falsely thinks need to be recompiled when you type make. Taken to an extreme, this can make cmake essentially useless with respect to reducing recompilation.

The result of including .h files in .h files is that (2) you have to recompile everything much more frequently and (1) it takes much longer to do so. It's a compounding effect.

To reduce these problems to a minimum, I recommend that we do as follows:

• Do not include a .h file in a .h file, which two exceptions:
  1. forward declaration headers.

     If you need to forward declare iostreams, use
     #include <iosfwd>. If you need array templates, use
     #include "arraysfwd".
     

  2. headers from classes from which you need to inherit.

     Note that there is no need to include headers of classes that you are merely referring to as arguments to a method or as members of a class. Just forward-declare the class and use pointers and references:

          MyClass;
          void myfunction(MyClass& myClass);
          class NewClass{
            MyClass *myClass;
          };
     

     To summarize, you only need to include a .h file in a .h file to access an interface.

Alec