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

From: David Abrahams (dave_at_[hidden])
Date: 2007-12-01 08:56:28

on Fri Nov 30 2007, Joel de Guzman <joel-AT-boost-consulting.com> wrote:

> Hi,
>
> As promised, here's a draft of the proposed
> "Boost Header And Namespace Policy" (attached)
> Comments, suggestions, etc. very welcome.

This is really great overall, Joel!  Just a few remarks...

> Regards,
> -- 
> Joel de Guzman
> http://www.boost-consulting.com
> http://spirit.sf.net
> Boost Header And Namespace Policy
>
> There has been an unwritten standard practice on header placement and
> namespaces that has been developed over the years. The Boost policy
> gives library authors a huge amount of freedom to organize and evolve
> their libraries as they see fit. Authors of newer libraries, however,
> had to try and figure out from the way existing libraries are
> structured or ask help from fellow boosters with more boost experience
> in "boostifying" their code. With very few exceptions, this worked
> well in the past. Library authors stayed within the bounds of the
> standard practice. Yet, with the rate Boost is growing, it would be
> crucial to put the Boost standard practice in writing to avoid
> confusion in the future.
>
> This short document will attempt to formalize the Boost standard
> practice on header placement, subdirectory and library organization,
> and namespace conventions. One purpose of the review process is to
> raise these issues at a proper time. It would be best to add adherence
> to the standard practice as part of the review.

Very nice so far.

> * Core libraries whose documented public interface fits in just a few
>   headers and a few pages of documentation can put all their public
>   headers in boost/ and their components in boost::.

I'd like to mildly discourage this practice for new core libraries.
Forwarding headers work well for that purpose and keep the file
structure cleaner.

>   For a core library named foobar, the convention is as follows:
>
>   - One or more (preferably one) header file(s). Example:
>
>     boost/foobar.hpp
>
>   - foobar components (classes, types, constants etc.) in
>     namespace boost. Example:
>
>     namespace boost
>     {
>         class foo {/*...*/};
>         class bar {/*...*/};
>     }
>
> 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.

The repetition of "library/ies" is confusing.  I think you should say
"The structure of every moderately-sized software project depends on
core components."

> Typically, "core" libraries have the highest number of dependencies.

You mean "dependents"

> Looking at the dependency
> diagram of boost, the core libraries will be at the bottommost 

Graphs don't have a bottommost.  How about "leaves?"

> with lots of other libraries pointing acyclically at it. 

I don't think one can "point acyclically" either.  Why not just say
"dependency DAG" above?

> It's a must
> to avoid having them depend on other libraries in other layers above
> the core. 

How about, "A core library must not depend on any non-core libraries?"

> 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.
>
> * Utility libraries whose documented public interface fits in just a few
>   headers and a few pages of documentation 

I would say, "in one header and less than a page of documentation."

>   can put all their public headers in boost/utility and their
>   components in boost::.

Again I'd like to mildly discourage that practice for the same
reasons.

>   For a utility library named foobar, the convention is as follows:
>
>   - One or more (preferably one) header file(s). Example:
>
>     boost/utility/foobar.hpp
>
>   - foobar components (classes, types, constants etc.) in
>     namespace boost. Example:
>
>     namespace boost
>     {
>         class foo {/*...*/};
>         class bar {/*...*/};
>     }
>
> All utility libraries pass through the same Boost review process.
> In certain occasions, a small library that are common to one or
> more Boost libraries and has already been in extensive use may
> undergo a "Fast track" review for inclusion as a boost utility.
>
> * Non-core libraries may 

Please add ", at the author's discretion,"  here.

>   place a single consolidated convenience 
>   header in boost/, forwarding to files of the form 
>   boost/<libraryname>/<header>.hpp.  Regardless, their documented
>   public components are not in boost/ or namespace boost::
>
>   For a library named foobar, the convention is as follows:
>
>   - A single boost/foobar.hpp that forwards to all the headers

    s/A single/An optional header/

>     of foobar:
>     
>     boost/foobar.hpp

What does writing boost/foobar.hpp again add here?

>   - foobar components (classes, types, constants etc.) in
>     namespace boost::foobar. Example:
>
>     namespace boost { namespace foobar
>     {
>         class foo {/*...*/};
>         class bar {/*...*/};
>     }}
>
>   - A subdirectory boost/foobar where all foobar headers are placed.
>
> * Un-reviewed implementation details of libraries have been placed in
>   boost/detail if they need to be used by other libraries and a
>   subdirectory of boost/<libraryname>/ otherwise. 

I don't think that's right.  What usually happens is that they get
placed in a subdirectory of boost/<libraryname>/  and then are moved
to boost/detail when someone discovers they want to use use them
outside of <libraryname>.

>   Their documented public components are placed in boost/detail and
>   namespace boost::detail.

what public components?  These are un-reviewed implementation
details.  I'm confused.

> * Libraries may host sub libraries that may be used by other boost

nit: "sub" is not a word, so that should be "sublibraries" or
"sub-libraries"

>   libraries. Such sub libraries are typically meant for future boost
>   review. Their documented public components are placed in
>   boost/<host-libraryname>/<libraryname>/<header>.hpp and
>   namespace boost::<libraryname>.
>
> One such example is the proto library that is hosted by xpressive.
> Another is fusion. The fusion library was once hosted by spirit. After
> passing the boost formal review the fusion library is now a full
> fledged boost library.

Again, this is really great.  I think while we're at it, we'd better
describe what happens under libs/, too.  But if you like, we can nail
down this part first.

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