C++ - Are there benefits of using #include <ClassName> instead of #include <classname.h>?

Question

I know that the standard libraries use includes with .h for the old C libraries and includes without .h for the up to date libraries. But what is the better practice for one's own classes?

Where I work we always had an include folder with two files per class: classname.h and ClassName. ClassName includes the classname.h and classname.h includes the real class header. To include a class you then use

#include <ClassName>

That's the way Qt does it, and I'm pretty sure Qt is the reason they started doing it in my company. But are there any benefits of that?

The drawbacks are pretty obvious, I think:

• One more file to create for a new class (we do it with a bash script, but still)
• One more file per class to manage
• When renaming a file/class via an IDE you usually have to adapt the ClassName file by hand (even Qt Creator can't do that)
• I have never seen this style anywhere other than the std library and Qt

Do you use this style? If so, why? What are arguments for it? Are there more arguments against it?

Answer 1

First, I'm going to make up a term and call it "Class-Specific Include File" or "CSIF". These files do not end in .h, even though they are used like a header, thus the "include file" part. Since I'm going to keep referring to the thing, I might as well give it an acronym, too.

How this is implemented in Qt

Qt has a "header" file with no extension for each defined Qt class or struct, known as CSIF for this answer. CSIFs go right into the \include path with normal header files, but they all do the same thing if you open one up. Let's start with with include files in QtWidgets, particularly the ones related to QStyleOption:

\include
    ...
    QStyleOption
    qstyleoption.h
    QStyleOptionButton
    QStyleOptionComboBox
    ...

If you open up one of those QStyleOption-related CSIFs, all contain one line of code:

#include "qstyleoption.h"

And in qstyleoption.h:

#include "../../src/widgets/styles/qstyleoption.h"

All that the CSIF does is #include the correct header from the source tree for the class it is named after. It creates a level of abstraction between the actual definition of the class and #include statement needed to use it. As a result, this code:

//In some .cpp file somewhere
#include <QStyleOptionButton>
#include <QStyleOptionComboBox>

includes the same header file (protected by guards, of course), but the developer using Qt doesn't need to know that. All the developer cares about is that s/he's using a class, and s/he wants to be certain that the class is available. I don't know if this was the original logic, but that's the effect it has.

Answers to your specific questions

1. Do you use this style? If so, why?
Yes, but only because the project I'm working on emulates the Qt library style, so that Qt developers can use it comfortably alongside Qt. Otherwise, [insert profuse swearing].

2. What are arguments for it?
The only good argument I know of for it is above, in how Qt uses it to abstract-away classes and the location of their definitions. As a user of Qt, ensuring I have the proper header files included is a breeze. If I use class QFoo, I include: <QFoo>. Simple.

3. Are there more arguments against it?
There are plenty of arguments against it, as you noted in your question.

• It makes refactoring many times harder.
• It's only truly useful if you're developing a library.
• It's only worth your time if your library has an API stability guarantee and is reasonably mature, because it makes refactoring many times harder.
• It means every class your library exports must have a CSIF, and missing one is easy to do.

I'm sure others can come up with more examples of CSIF making life difficult. In all, one must weigh the balance of the increased rigidity it creates in your library and the benefits to the end-developer before making a decision.

As for how your workplace uses it... I'm shrugging. Someone copied the Qt style without understanding why, perhaps?