Re: [boost] test_main.cpp (was Review: Function library)

From: John Max Skaller (skaller_at_[hidden])
Date: 2001-06-14 16:38:11

Beman Dawes wrote:

> Interesting.  I don't remember ever hearing any suggested practice for
> ordering of #includes.

I have: I attended an inhouse talk by a programmer
who made a very strong case for including standard headers
_after_ application specific ones. I was quite surprised,
because my natural inclinations were otherwise.

Darin Adler wrote:

 >I include the corresponding
 >header first, before any standard headers. 

 >This helps make sure you don't forget to include it, 
 >and also provides a rudimentary "does this header
 >include enough things to stand alone" check. 

The argument I heard was similar but strengthened by
considering changes, decoupling, information hiding
and abstraction.

The first file to include is the interface which you want
to implement. It may use types it _doesn't_ define: 
it just says

        class X;

and uses pointers to X. To implement some of the
methods specified in the class, you may actually
have to call methods on X objects, so you 
include the header for X next.

...

At the bottom of the chain are low level implementation
details like the need for memcpy. So the standard
headers come last.

What this means is that if you change implementation
details, you may need to change the standard headers
you include (at the end of the list of headers).

If you change some of the pointers of you class,
you may need class Y instead of X, so the middle
tier includes may change. 

Hopefully, the first file, naming the interface
being implemented, will never change.

So basically, the most solid requirements (most abstract)
come  first, and the most detailed last: and thats not
the last header file, but the actual code implementing
the interface:

        #include my interface
        #include my projects subsystems used to implement it
        #include standard headers
        actual implementation

The top changes slowest, the bottom fastest.
This is a form of 'information hiding' which allows
decoupling: the 'implementation details' are closest
together. [The standard headers are purely to
provide tools to implement your interface: if your
abstraction 'my interface' needed some standard
headers, it would have included them independently]

--
John (Max) Skaller, mailto:skaller_at_[hidden]
10/1 Toxteth Rd Glebe NSW 2037 Australia voice: 61-2-9660-0850
checkout Vyper http://Vyper.sourceforge.net
download Interscript http://Interscript.sourceforge.net