Re: [boost] Boost policy for putting headers in boost/ Was: #3541 Support <boost/ptr_map.hpp>

Subject: Re: [boost] Boost policy for putting headers in boost/ Was: #3541 Support <boost/ptr_map.hpp>
From: Joel de Guzman (joel_at_[hidden])
Date: 2009-10-28 04:21:29

David Abrahams wrote:
> on Mon Oct 26 2009, Joel de Guzman <joel-AT-boost-consulting.com> wrote:
> 
>> FWIW, we've solved that by having a flat include directory. It's the
>> include/ dir you see up there. The directory contains all forwarding
>> headers. For instance, see http://tinyurl.com/yj86r8v. You have:
>>
>>     #include <boost/fusion/include/deref.hpp>
>>
>> in addition to the modular:
>>
>>     #include <boost/fusion/iterator/deref.hpp>
> 
> Oh yeah, I forgot about that.  Not bad, but the problem is... I tend to
> forget it.  So I reach for boost/fusion/deref.hpp as though all
> libraries use that convention, and I am slowed down until I can remind
> myself that fusion is different.  Consistency in these little things
> goes a long way toward ease-of-use.

It's always a balance. I advocate a clean modular structure as much
as I advocate ease of use. I think the clean layout of Fusion is
one of the reasons why people easily get what's going on and
the barrier to contributing back to the code-base is lower. If one
wants to understand iterators or sequences, they need to look at
the headers in only one directory, not distributed all over the place.

I also advocate consistency. That is why I chose that structure.
It's not different at all, if you think in terms of modularity.
Boost is a set of libraries; each library is composed of smaller
sub-libraries or components, and so on. The (outermost) main boost
goes like this:

     boost/
         libx/
         liby/
         libx.hpp
         liby.hpp

Some libraries, especially the bigger ones really ought to
be broken down into sub-libraries or modules. Following the
main header convention, it goes the same for sub-libraries,
e.g.:

     boost/
         libx/
             modx/
             mody/
             modx.hpp
             mody.hpp
         liby/
         libx.hpp
         liby.hpp

You only have one consistent header policy (i.e sub-modules
are no different than main modules). If you think about it in
that regard, boost/fusion/deref.hpp is actually inconsistent.
A header such as boost/libname/foo.hpp is only consistent if
libname is monolithic (does not comprise of smaller modules or
sub-libraries). IMHO, that is good only for small libraries.

Regards,
-- 
Joel de Guzman
http://www.boostpro.com
http://spirit.sf.net
http://www.facebook.com/djowel
Meet me at BoostCon
http://www.boostcon.com/home
http://www.facebook.com/boostcon