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: David Abrahams (dave_at_[hidden])
Date: 2009-10-28 13:44:30

on Wed Oct 28 2009, Joel de Guzman <joel-AT-boost-consulting.com> wrote:

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

Of course I understand the rationale.  

> I also advocate consistency. That is why I chose that structure.
> It's not different at all, if you think in terms of modularity.

I have a hard time swallowing that assertion.  Your organization makes
sense, but please don't deny reality by claiming it's not different
from other Boost libraries that established precedent.

If you really wanted to be consistent with type_traits, MPL,
Bost.Python, et. al., you could have kept all your nice modular
structure but moved the headers that are in boost/fusion/include into
boost/fusion.  Your organization may in fact be superior from a logical
standpoint, but the difference from precedent has downsides.

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

inconsistent with what?

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

Works for MPL.  Nobody ever wonders where to find anything in MPL.  I
doubt you can say the same for Fusion.  There's an extra learning hump
to get over and more information to absorb.  Not only do I have to know
about boost::fusion::invoke if I want to use it, but I either to
remember that Fusion has a funky include/ subdirectory where I can find
invoke.hpp, or I need to remember that invoke is part of the
"functional" module and include fusion/functional.hpp, or that it's in
fusion/functional/invocation.hpp, or finally in
fusion/functional/invocation/invoke.hpp.

I don't care (very much) which convention we choose, but I would very
much prefer, for our users' sake, to choose one uniform #include
convention that works for all the libraries.

-- 
Dave Abrahams           Meet me at BoostCon: http://www.boostcon.com
BoostPro Computing
http://www.boostpro.com