[boost] Re: Namespaces vs. directory placement

From: David Abrahams (dave_at_[hidden])
Date: 2004-12-29 02:55:53

Jonathan Turkanis wrote:
> David Abrahams wrote:
>> Jonathan Turkanis wrote:
>>> Jonathan Turkanis wrote:
>>>
>>>> Okay, if there are no objections, this is what I'll do.
>>>
>>> This didn't come out quite right -- I know that Daryle has objected.
>>>
>>> I guess I mean: given the fact that the namespace-directory
>>> convention has already been widely violated, if there are no further
>>> objections I'll keep the library in the iostreams directory but use
>>> the io namespace.
>>
>> I didn't see the whole thread, but we ought to try to avoid violating
>> the convention any more than it has been.  As Boost grows, this
>> becomes more important.  What's wrong with a namespace
>> boost::iostreams?  You can always introduce an alias for backward
>> compatibility.
> 
> Since you didn't see the whole thread, let me quote myself:
> 
> Jonathan Turkanis wrote:
>> 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
>>    (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) is particularly important, since the documentation will contain a lot of
> tutorial material in which the namespace qualification can't be omitted, e.g.,
> 
>     template<typename Sink>
>     void put(Sink& dest, int c)
>     {
>         if (c == '\n')
>             col_no_ = 0;
>         else {
>             if (col_no_ >= line_length_)
>                 this->put(dest, '\n');
>             ++col_no_;
>         }
>         boost::io::put(dest, c);
>     }

Pshaw.  After a few pages C++ Template Metaprogramming has an example
that begins with:

  namespace mpl = boost::mpl; // namespace alias

which it then follows with a note that says

  "Many examples in this book will use ``mpl::`` to indicate
  ``boost::mpl::``, but will omit the alias that makes it legal
  C++."

> The occurence of boost::io::put in the above example has to be qualified, since
> otherwise it will refer to the member function being defined. I worry that
> having to use a long namespace name or to introduce a namespace alias in a high
> percentage of the examples will make the documentation harder to follow, and the
> library harder to learn.

So use the technique described above.  And if you really can't stand
that, do as I suggested originally and introduce the alias in Boost:

namespace boost { namespace iostreams{} namespace io = iostreams; }

> If I have to choose, then, I would much rather use the namespace io and move the
> library back to boost/io than use the namespace iostreams.

You don't _have_ to choose, but then you could do better than the status
quo.

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com