[Development] Rules for including private headers

[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#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.
------------------------------------------------------------------