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