Should I always define my entire template class in the header file?

Question

For some reason, it seems that C++ doesn't like it when you split a template class (i.e. a class declared as template <typename T> class Thing) into a .h and a .cpp file, like you would do with any other class.

Does that mean that when writing a template class, I should just write it all in the header file? What do C++ programmers do in these cases?

EDIT: I understand that there are alternatives to writing it all in the .h file. But what's the best option? Or what the most common option?

Answer 1

It is popular to split the definition of a template out into another file. It is so popular it may even be the most common practice, but I am not positive about that.

I think this is poor practice (as opposed to putting the definitions in the same header) for the following reasons.

My priorities when writing code are (most important first):

1. Correctness.
2. Run time performance.
3. Compile time performance.
4. Maintainability / Easy to read.
5. Easy to write.

As long as the template definition is in the same header, or in another file that the header includes, the number one priority Correctness is not impacted one way or the other.

The second priority Run time performance is not impacted in the least.

The third priority Compile time performance is negatively impacted by putting the definition in a separate file. By how much is debatable. But there is no way that a compiler can compile X amount of code and open/close two files, as fast as it can compile the exact same code while opening/closing only one file. A friend of mine who is an excellent compiler writer once told me that the slowest thing I could ask his compiler to do was to open a file. This was before we did as much compile-time computation as we do today, but still...

The fourth priority Maintainability / Easy to read is quite subjective. But in my opinion a separate file is a negative impact on this priority. When I'm reading code, it is typically easier for me to understand it if it is all in one file. And I really get annoyed when I have to go hunting for the file when its name or location is not obvious. And I get even more annoyed when the definition is split into many files. For my money, one file optimizes this priority.

The fifth priority Easy to write is also quite subjective. I don't see much advantage either way on this one. It is very slightly easier to put everything in one file. But it is certainly not difficult to create a new file. I give the "one file approach" a very slight advantage on this priority.

So in summary, out of my five priorities, the two most important, this decision makes absolutely no difference on, and separate files have small negative consequences for the 3 lower priorities. Of the 3 lower priorities, the most important of these, compile-time performance is objectively negatively impacted. The two lowest priorities are admittedly subjective as to whether or not they are positively or negatively impacted.

I see no benefit and a small cost to putting your template definitions in a separate header.

Answer 2

"Does that mean that when writing a template class, I should just write it all in the header file? What do C++ programmers do in these cases?"

What you can do (and is wide spread/popular practice), is separate implementation code out to special template implementation files, that will in turn be in íncluded by the template headers, containing the declarations.
The gain of this technique is considered little for most of the cases, though it has it's points, if you want to hide the implementation details and not spill header files to become large.

The point is not to have the template definition code, or specializations in separate translation units, such these can be seen directly by other translation units, including the template header file.

The common pattern is

MyTemplate.h

#if !defined(MYTEMPLATE_H_)
#define MYTEMPLATE_H_
namespace myspace {
    template <typename T> 
    class MyTemplate {
    public:
        void foo(T value);
    };

#include "MyTemplate.tcc"
}
#endif // MYTEMPLATE_H_

MyTemplate.tcc

// NOTE:  There aren't header guards for this file intentionally!
template<typename T>
void MyTemplate<T>::foo(T value) {
   // ...
}

Other popular extensions for template implementation files are .icc, .ipp, .impl. Just important, it shouldn't be .cpp, since most IDE's or build system frameworks will track this as translation unit, unless it's explicitly excluded (here's a sample why).

---

"So simply instead of the .cpp #includeing the header, the header #includes the .tpp (which contains the implementations)?"

Template classes work a bit differently regarding the ODR (one definition rule). Regular header files, that provide class declarations shouldn't contain implementations because the ODR would be violated when these are included from different translation units:

MyClass.h

class MyClass {
public:
    void foo(int);
};

// Violates ODR if MyClass.h is included from different translation units (.cpp files)
void MyClass::foo(int param) {
}

The templated version

template<typename T>
class MyClass {
public:
    void foo(T);
};

// Doesn't violate ODR if MyClass.h is included from different translation units 
// (.cpp files), since the template parameter isn't instatiated here yet.
template<typename T>
void MyClass<T>::foo(T param) {
}

As soon one translation unit instantiated something like MyClass<int>, other translation units instatiating the same template signature, will use the 1st one seen.

The latter implementation part could be replaced with an #include "MyClass.impl" that contains that code, if you think it messes up readability or maintainability of your header file too much.

_{As a minor drawback of the #include "MyClass.tcc" technique, you should notice, that most of the popular IDE's handle syntax highlighting and intellisense poorly for these kind of template implementation files.}