[Development] Rules for including private headers

[Frederik Gladhorn]

Fredag 14. februar 2014 11.03.02 skrev Ulf Hermann:
> Hello,
> 
> as I just got bitten by it (see
> https://codereview.qt-project.org/#change,78128) I'd really like to
> clarify our rules for including private headers in Qt.
> http://qt-project.org/wiki/Coding-Conventions#32bc73e08b315a2d85bfd10b2e8c86
> 7a has a few notes on that but they're not very conclusive. I don't really
> understand why qt_x11_p.h needs a separate rule. In general I propose an
> extension of that paragraph:

Sounds good to me. From what I read below, you just add the section about 
private headers, right?

> 
> ----------------------------------------------------------------------
> 
> Including Headers
> =================
> 
> Rules of thumb
> --------------
> 
> * In public header files, always use this form to include Qt headers:
> #include <QtCore/qwhatever.h>. The library prefix is neccessary for Mac
> OS X frameworks and is very convenient for non-qmake projects.
> 
> * In source files, include specialized headers first, then generic
> headers. Separate the categories with empty lines.
> 
>              #include <qstring.h> // Qt class
> 
>              #include <new> // STL stuff
> 
>              #include <limits.h> // system stuff
> 
> * If you need to include qplatformdefs.h, always include it as the first
> header file.
> 
> * If you need to include qt_x11_p.h, always include it as the last
> header file.
This could go into the private headers section since it's private itself.

> Including private headers
> -------------------------
> 
> If you need to include private headers there are four cases with
> different syntax. Various build system magic makes those possible but
> that will not be discussed here.
> 
> 1. The header, e.g. whatever_p.h, is in the same directory as the file
> including it. In this case write:
> 
>              #include "whatever_p.h"
> 
> 2. The header is in a different directory but in the same module. In
> this case locate the base directory of the module and include relative
> to that with quotation marks:
> 
>              #include "foo/bar/whatever_p.h"
> 
> foo is a subdirectory of the same directory the .pro file is in if
> you're using qmake.
> 
> 3. You want to include a private header from a different module, e.g.
> QtCore. Be careful with that as it creates interdependency between
> modules. If you're sure you need to do that make sure the project
> dependencies are set up correctly and include like this:
> 
>              #include <QtCore/private/whatever_p.h>
> 
> It doesn't matter if whatever_p.h is in the base directory of its
> project or in some subdirectory foo/bar/.
> 
> 4. You want to include a private header from a different project in the
> same module. This happens frequently when writing writing a test case or
> an example. If that's not what you're doing you should be careful, see
> 3. In that case:
> 
>              #include <private/whatever_p.h>
> 
> Again, the exact location of whatever_p.h doesn't matter.
> 
> ----------------------------------------------------------------------