[boost] Header Inclusion practices

Subject: [boost] Header Inclusion practices
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-04-11 17:55:58

As long as I can remember, it's been my practice to write program code 
to minimize dependencies on the environment in which it is built.  By 
environment I mean things external to the code itself like environmental 
and command line variables, directory context etc.  As part of this I 
use rules for header file inclusion:

a) use #include "header.hpp" for files in the same directory as the 
current source file.

b) use #include "other directory/header.hpp" for files which are known 
to be in a specific place relative to the current file.  This shows up 
in things like: #include "../include/header.hpp" for tests and examples.

c) use #include <boost/serialization/xml_archive.hpp> for files which 
are found by looking in directories listed in "-I" switches and 
environmental variables (INCLUDE).  I generally try not to depend upon 
any environmental variables as I always forget to set them or even how 
to set them.  Come to think about it.  I don't know how my build system 
finds the boost libraries.  I presume it's through some IDE/Bjam/CMake 
setting which I can never remember.

d) use #include <iostream> for standard library components.  Presumably 
these are routed to some directory relative to the compiler.

So some of my source files look like:

// interval.hpp header for safe numerics library

#include <limits>
#include <cassert>
#include <type_traits>
#include <array>
#include <initializer_list>

#include <boost/logic/tribool.hpp>
#include <boost/core/demangle.hpp>

#include "utility.hpp" // log
#include "checked_result.hpp"
#include "checked.hpp"

and

// example using he safe numerics library

#include <iostream>
#include <limits>
#include <boost/integer.hpp>

#include "../include/cpp.hpp"
#include "../include/exception.hpp"
#include "../include/safe_integer.hpp"
#include "../include/safe_range.hpp"

This has raised consternation in some quarters - but I don't see 
anything wrong with it.  It basically means that only the <boost 
libraries are depended on the whole b2 business.  I didn't want the 
incubator version of the the safe numeric library to depend on the 
library having been accepted into boost have have b2 run.  Also I don't 
like adding the library to boost - and having to change all the headers. 
  What if someone want's to run the tests/examples outside of the boost 
tree.

As far as I know this question has never been asked before and I'm 
curious to know what others might have to say about this.

Robert Ramey