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 14:54:51

David Abrahams wrote:
> 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.

I'm not sure I can swallow that either. AFAIR, it was spirit that
was one of the first libraries to include sub-libraries. At that
time, there was no established precedent yet (for non monolithic
libraries). That was roughly at the same time when MPL was taking
shape IIRC. Fusion just followed through the spirit organizational
structure and at the same time borrowed/stole much of the best
from MPL.

> 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

I agree, and it's a trade off. That is why we introduced the include
directory of flat includes.

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

Agreed. Again, this is the point where modularity and ease of
use are counteracting forces. Yet, we just can't throw one for the
other. I still believe a good compromise is the include directory.

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

Much of this is highly subjective. I tried once to formulate a
header/namespace policy that will be uniform for all. What I found
is that a consensus is very difficult to reach. It's almost the
same as naming guidelines. Tough! Some folks are very religious on
this, even. I can be ok with whatever is consensus as long as you
don't force me to give up the modular structure of the libraries I
am concerned with.

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