[Development] Rules for including private headers

Laszlo Papp lpapp at kde.org
Sat Feb 15 20:44:05 CET 2014


On Fri, Feb 14, 2014 at 10:03 AM, Ulf Hermann <ulf.hermann at digia.com> wrote:
> 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#32bc73e08b315a2d85bfd10b2e8c867a
> 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:
>
> ----------------------------------------------------------------------
>
> 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.
>
> 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.
>
> ----------------------------------------------------------------------
>
> --
> Ulf Hermann, Software Engineer - Digia, Qt
> Digia Germany GmbH, Rudower Chaussee 13, D-12489 Berlin
> Geschäftsführer: Mika Pälsi, Juha Varelius, Tuula Haataja
> Registergericht: Amtsgericht Charlottenburg, HRB 144331 B,
>
> Digia Germany is a group company of Digia Plc,
> Valimotie 21, FI-00380 Helsinki Finland
> ------------------------------------------------------------------
> PRIVACY AND CONFIDENTIALITY NOTICE
> This message and any attachments are intended only for use by the named
> addressee and may contain privileged and/or confidential information. If
> you are not the named addressee you should not disseminate, copy or take
> any action in reliance on it. If you have received this message in
> error, please contact the sender immediately and delete the message and
> any attachments accompanying it. Digia Germany GmbH and Digia Plc do not
> accept liability for any corruption, interception, amendment, tampering
> or viruses occurring to this message.
> ------------------------------------------------------------------

Hmm, I have just coincidentally seen this thread after the submission
of a change where I was thinking a bit about the inclusion order. It
is a bit tricky case because it is for Qt 5 and Qt 4 support, but any
review is welcome whether or not it is good:
https://codereview.qt-project.org/#patch,all,78278,6

(I am not an expert about this)



More information about the Development mailing list