Re: [boost] [RFC] Header/namespace policy draft

From: Joel de Guzman (joel_at_[hidden])
Date: 2007-12-01 03:25:28

Mat Marcus wrote:
> On Nov 30, 2007 8:47 PM, Joel de Guzman <joel_at_[hidden]> wrote:
>> Hi,
>>
>> As promised, here's a draft of the proposed
>> "Boost Header And Namespace Policy" (attached)
>> Comments, suggestions, etc. very welcome.
> 
> [snip]
> 
>> The concept of "core library" is not new. boost::shared_ptr, for
>> example, is a core library. It's pretty much common to all libraries.
>> Having a core library gives us structure. Typically, "core" libraries
>> have the highest number of dependencies. Looking at the dependency
>> diagram of boost, the core libraries will be at the bottommost with
>> lots of other libraries pointing acyclically at it. It's a must to
>> avoid having them depend on other libraries in other layers above the
>> core. More emphasis and constraints must be given to these "core"
>> libraries as they form the backbone of boost as a whole. For instance,
>> a broken core library will have disastrous effects on the whole Boost
>> library --core libraries should be very stable.
>>
>> Determining wether a library is core can be part of the review. If the
>> author of a library intends it to be a "core" library, he can
>> explicitly say so and be subject for the review. A core library will
>> have to accept more stringent requirements such as stability and
>> non-dependence on other non-core libraries.
> [snip]
> 
> This raises an interesting question for me. I recently received a bug
> report against boost-dependent library that I work on (Adobe Source
> Libraries). One of our components supports move semantics. It makes
> use of a free function named move in namespace adobe. We were calling
> it unqualified from within other library routines. With boost 1.35
> this will have to change. Why? Because some classes in the adobe
> library inherit from boost::equality_comparable. As a result, when
> adobe::move is called with such boost-derived classes, ADL pulls in
> the boost namespace and an ambiguity arises against the boost::move
> supplied by boost::thread. One might argue that best practice in the
> face of ADL is to be defensive and to avoid unqualified calls (when
> replaceability is not the intent). In fact, I will do just this for
> our next release.  However this would be a little bit more pleasant if
> thread's boost::move was intended as a documented boost-wide
> move-semantics component. In fact we might consider dropping our own
> move component if such a boost component existed. At present however,
> it appears that the boost::move is more of a detail of boost/thread.
> Are we sure that now is the time to put move in the top level boost
> namespace?
> 
> Thoughts?

If the thread library's move function is undocumented, then it has
no business being in the root boost namespace but in boost::detail.
If indeed that is the case, I consider it a bug that should be fixed.
We should be more vigilant in the review period on such violations.
More stringent requirements should be put in place for core libraries.
We should try to restrict as much as possible what goes into the
boost root namespace and directory. I think it's best to add:

     Only reviewed and documented components of a core library may be
     placed in the root boost namespace. Violations are considered bugs
     that must be fixed.

in our core libraries policies.

((I did a quick search in boost thread's docs and indeed move is not
documented.))

Regards,
-- 
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net