Re: [boost] Namespaces vs. directory placement (was: Re: [iostreams] Version of Iostreams compatible with 1.32 available)

From: Daryle Walker (darylew_at_[hidden])
Date: 2004-12-21 00:59:21

On 12/20/04 8:58 PM, "Jonathan Turkanis" <technews_at_[hidden]> wrote:

> Daryle Walker wrote:
>> On 12/10/04 2:44 AM, "Joaquín Mª López Muñoz" <joaquin_at_[hidden]> wrote:
>> 
>>> Hi Jonathan, some quick observations:
>>> 
>>> * Some of your includes still refer to <boost/io/...> instead of
>>> <boost/iostreams/...> (most notably, the examples). Am I missing something?
>> [TRUNCATE]
>> 
>> I looked at some code.  Files are in the "boost/iostreams/..." directory, but
>> the items are in the "boost::io::..." namespace. We're trying to keep the
>> directory and namespace hierarchies in line so it's easy for users to find
>> stuff.  The policy started from the base header directory getting too many
>> direct entries for easy searching.
> 
> The main reason Jeff recommended that I switch to the "iostreams" directory,
> IIRC, was that it would be difficult to merge our documentation: either the
> state-savers would get lost as a small component of the iostreams library, or
> we would have to have an introductory page with links to both libraries.

Maybe the latter.  (And don't forget that the introductory page would
include the format library, which also shares "boost::io".)  Eventually, the
state-savers, the new iostreams, and the format libraries could all switch
to Doxygen & BoostBook.

Actually, the co-existence policy of libraries that share a closure is
something we all have to consider.  The basic class/function reference, done
by Doxygen or the like, of all Boost code could eventually be unified.  But
what do we do with the explanation prose?

> I would greatly prefer to use the namespace  "boost::io" because:
> 
> (i) it is much shorter than "boost::iostreams"; while it is possible to use an
> alias to shorten it, I'd hate to make users do this when there is a perfectly
> suitable short name available.
> (ii) there currently are not many declarations in the namespace "boost::io",
> so there is not much chance of collisions

If someone in the future doesn't realize that this library doesn't follow
the pattern, then they could accidentally add a collision.

> (iii) it is a more accurate discription of the library, since the core
> infrastructure is independent of the standard iostreams library and might be
> used without streams, e.g., for async i/o.
> 
> I also don't think finding the iostreams library or its namespace will be a
> serious problem.
> 
> Therefore, unless there is a very convincing reason to enforce the policy that
> namespaces match directories in this particular case, I'd like to use
> "boost::io".

There was originally no problem with everyone putting their headers directly
in the header directory, but it didn't scale as Boost grew.  Having a dozen
or so people follow your lead over the next few years could result in a new
version of the scaling problem.  (I'm trying to stop a potential big problem
while it's only tiny.)

-- 
Daryle Walker
Mac, Internet, and Video Game Junkie
darylew AT hotmail DOT com