Code should be organized to accelerate compilation.

[alecjohnson]

I am creating this issue as a header under which to check in future modifications for the purpose of accelerating compilation.

We can accelerate compilation and recompilation by observing the following principles.

Avoid including a .h file from a .h file. This hurts compilation speed in two ways.

First, recompilation speed is hurt if including unnecessary header files, because cmake thinks that every header file inclusion represents an actual code dependency.

Second, compilation speed is hurt when the included header files expand to a large number of lines, because in many compilers the preprocessor must process all the included files.

In particular, the C++ stream header files are notoriously bloated, typically expanding to 20000 lines that the preprocessor must parse for every .cpp file (object module) unless sophisticated techniques are used such as precompiled headers. It is better not to write code that assumes a sophisticated compiler.

This leads to the second principle: Avoid creating a large number of .cpp (implementation) files that include large header files.

If we want to put every class implementation in its own implementation file, then we should avoid including the iostream class except in classes that are really doing file I/O and are not just printing error messages. One of the reasons that I implemented the functionality in #include "error.h", which defines eprintf(), invalid_value_error(), and unsupported_value_error() methods (see issue #29), was to avoid the need to include iostream classes merely to print simple error messages.

In general, we can accelerate computation by separating out declarations and headers and consolidating implementation files. For example, if class A needs to contain an instance of class B, if you make A contain a pointer to class B then you do not need to include B.h in A.h; you only need to make the forward declaration class B; in A.h. If a large number of small classes need the same large set of header files, it may be appropriate to implement them all in a common .cpp file.

I more than doubled the speed of compilation of another software package (DoGPack) by implementing changes along these lines.