Is anyone familiar with the "implementation/internal header" (*.ih)?

In the half-year C++ course by F.B. Brokken (author of The C++ Annotations), we have been taught the use of so-called implementation headers. I knew that this is a convention by Frank, but I have literally NEVER seen it anywhere else. I'll therefore explain the concept and I'm very curious about what other people make of this.

The idea is that you just put all #include directives that are needed by the implementations of your class-members' implementations (assuming you're not writing in-class definitions) in one file, the .ih implementation header, and #include this file in every source file instead. The alternatives are 1) #include everything in the class-header or 2) #include all headers seperately in every source-file.

The downsides to both alternatives are obvious: 1a) You have to recompile all sources #include'ing this header after adding anything that requires some additional #include's. 1b) Your header file, that is supposed to be a clear interface of your class, gets polluted with a great bunch of #include directives of which the user has no idea what they are used for, nor does he care. 2a) You have to #include the same headers again and again in each source file. 2b) Your implementation is polluted by all these #include's, making it look just a little messy.

Just to be clear:

/* someclass.h(pp) */

#ifndef SOME_CLASS_H
#define SOME_CLASS_H

class SomeClass
{
    //some private data members
    public:
        SomeClass();
        void sayHi() const;
        // some more member functions
    private:
        // some private member functions
};

#endif

/* someclass.ih */

#include "someclass.h"
#include <iostream>
#include <vector>
using namespace std; 

// namespace is now only used in my implementations, other people
// including my headers won't accidentally import the entire std namespace.

/* sayhi.cc */

#include "someclass.ih"

void SomeClass::sayHi() const
{
     cout << "sayHi() says hi!\n";
}

Now, again, the question is: has anyone ever heard of such a convention? Did I convince anyone to start using it? I personally find it a very useful (even obvious) convention and I'm a little surprised that I haven't seen it anywhere else.

Answers


Interesting postings. Let me begin by commenting on user1428839's (referred to as poster below) statements about the .ih headers:

To begin with, poster writes:

...The idea is that you just put all #include directives that are needed by the implementations of your class-members' implementations ... in one file, the .ih implementation header, and #include this file in every source file instead.

As formulated, this is not true. To avoid confusion, the last part of the sentence should be: ... in every source file of the class to which the .ih file belongs. Under the .ih approach the class header file (say, someclass.h) merely offers the interface and should only declare what can be declared. So, if SomeClass has a class data member std::ofstream *d_out then there's no need to #include <fstream>. Instead, it suffices to #include <iosfwd>. This results in a clean class interface, minimizing its compilation time when included by sources not belonging to, but merely using SomeClass.

Next, poster states:

1a) You have to recompile all sources #include'ing this header after adding anything that requires some additional #include's.

That's not really true. This is only required if features declared by the additional header are actually used in the interface. If that's not true then a full recompilation is not required. Full recompilation is required if new data members are added or (but that's bad style, e.g., you're using inline members) elements of the additional header are used in the class interface.

Next point raised by poster:

1b) Your header file, that is supposed to be a clear interface of your class, gets polluted with a great bunch of #include directives of which the user has no idea what they are used for, nor does he care.

Correct, but the important point here is that the class header becomes too fat. Every time an external source needs to include someclass.h the compiler must also read all those additional headers, and those included by those headers, etc., whereas it only needs to know what the essentials of SomeClass are. The adage being that the user should not have to pay for what he/she doesn't need, in this case additional compilation time caused by the compiler having to read (often many) useless (in the context of SomeClass) header files.

One of the alternatives to using the .ih convention suggested by poster is to include what you need where you need it. In fact I think this is a good alternative, but it also makes for a lot of bookkeeping and work. Usually class member implementations require the same header files, and putting them in one file, the implementation header has the added benefit of defining one point of maintenance. Yes, there will be a small overhead when occasionally the compiler has to read a header a particular source doesn't need, but that happens only once: at class compilation time, which (hopefully, presumably) only happens occasionally.

I'm afraid some of the reactions to poster's posting are the result of slightly misunderstanding the .ih approach's core points:

  • The class header itself remains as slim as possible
  • Sources using the class don't suffer from longer compilation times than strictly required
  • The class developer doesn't have to include, time and again, a bunch of headers required for compiling the class's members. Instead, only one header, tailored to the class's requirements, needs to be included.

Another reply (by DeadMG) focussed on putting all sources into one source file. Up to a point this is a matter of style. If you develop software for one particular program then you might as well put all your sources into one file, if that suits your personal taste. I personally find it very annoying and hard to work with those files, as I often like to see or work with the sources of many functions in parallel, but in the end it's of course a matter of taste.

However, if you develop software with the intent of reusing it later in additional programs, e.g., you develop a class which the thought of adding it to a library in mind, then you definitely should use the one-function-one-file scheme. Consider constructors: classes usually offer a series of constructors, and you pick the one that suits your context. If the class's implementation is put into one source file then your final program will be unduly fat, as the linker will have to add the object file implementing your constructor to your program, as well as the object file(s) required by that program, etc, etc.. So you end up with a program which is, completely pointlessly, linked to many, many additional object files. The one-function-one-file principle prevents this from happening.


I have never seen this used anywhere, ever. Most classes have all their implemented functions in one file, so they don't have a problem with specifying the necessary headers repeatedly.


I don't get it. What happens the moment you have class members or class method parameters that use classes or struts or typedefs from other headers? And, add on the issues of recompilation... This seems like more work for les gain. You should be including only what the header needs in the header, and only what the implementation needs in the impl. That's it.


Need Your Help

python bit array (performant)

python performance bitarray bloom-filter

I'm designing a bloom filter and I'm wondering what the most performant bit array implementation is in Python.

GtkWarning could not open display - how can I notify-send from my daemon

linux ubuntu python-2.7 gtk upstart

I have a python-2.7.4 daemon script that uses the following command: