[Ayatana-dev] [C++][Review Guidelines] Header files and includes

[Tim Penhey <tim.penhey@xxxxxxxxxxxxx>]

Header files are used to define the public interface.

Header files introduce dependencies to your code base.  Ideally we want the 
bare minimum included or specified in header files.  If possible, it is better 
to forward declare a type than to include the header file for it.

Here are some good guidelines for dealing with header files.

General header guidelines:
 * Use "A" style for local includes, and <A> for system includes.
 * Don't include what you don't use
   - this adds dependencies where they aren't needed and significantly 
increases compilation time
   - This means "single library includes are a bad idea", even for the various 
nux libraries and unity core

For header files themselves:
 * forward declare types if you can
   -  i.e. those you use with a pointer or reference
 * include system files that you use
   - if you use std::map, include <map> and don't rely on transitive inclusion 
(i.e. if you are using "A" and "A" uses <map>, you should still include <map> 
as you are using it.  The include guards make the compiler handle this 
correctly.)
   - the reason for this is that "A" may stop using <map> and you don't want 
that to break your code.
 * Use interfaces or the pimpl pattern to introduce compiler firewalls (this is 
where the implementation details don't leak into the header files and introduce 
a dependency between how a class is implemented, and all the places where that 
class is used.

For source files:
 * The first include should be the definition header
    - i.e. for MyCoolClass.cpp, the first include should be "MyCoolClass.h"
 * Next somes C++ system headers, <string>, <vector>, <cmath>
 * Next comes dependent libraries, glib, boost, dbus, nux, unity-core
 * Next comes local dependencies, other project classes
 * Bonus points for alphabetical order within groups

Compilation time is a handy thing to get down as it can increase personal 
velocity when working.  I know of projects where just fixing the header 
includes, and only including what was necessary took compile times down by a 
factor of 10 - a 90 minute compile down to 10 minutes.

Tim

Attachment: signature.asc
Description: This is a digitally signed message part.