C++ – Is an 8 second (incremental) build time common

My view...

• Document how to use the function in the header file, or more accurately close to the declaration.

• Document how the function works (if it's not obvious from the code) in the source file, or more accurately, close to the definition.

For the birds-eye thing in the header, you don't necessarily need the documentation that close - you can document groups of declarations at once.

Broadly speaking, the caller should be interested in errors and exceptions (if only so they can be translated as they propogate through the layers of abstraction) so these should be documented close to the relevant declarations.

If your templates parameters can only assume a finite (and small) set of values, you could move their definition in a source file, and use explicit instantiation.

For instance, in aaa.h you only declare the template functions f and g:

template <int n>
int f();

template <class T>
void g(int a);

Assume n template parameter can only be 1, 3, 6, and T template parameter can only be int, long and void *.

Then you define them in aaa.cpp like this:

template <int n>
int f()
{
    ...
}

template <class T>
void g(int a)
{
    ...
}

template int f<1>();
template int f<3>();
template int f<6>();

template void g<int>(int a);
template void g<long>(int a);
template void g<void *>(int a);

In this way the compiler instantiates the template for the given parameters when compiling aaa.cpp. When compiling client code, it assumes that the definitions exist somewhere, and the linker will take care of that.

#include "aaa.h"

int main()
{
    f<1>();
    f<3>();
    f<6>();

    g<int>(5);
    g<long>(5);
    g<void *>(5);
}

You can explicitly instantiate template classes too. The drawback is that you can not use f or g with other template parameters.

#include "aaa.h"

int main()
{
    f<5>();
}

results in

undefined reference to `int f<5>()'

I used this technique in a project where few complex classes depended on a small (< 10) set of integer template parameters, and it significantly reduced compilation time (since the compiler did not have to parse the complex template definitions when compiling the client code). Of course you may get lesser improvements, depending on the actual code.