Re: [boost] Re: policy and rationale for directory and namespace organization?

From: Beman Dawes (bdawes_at_[hidden])
Date: 2001-09-26 06:48:41

At 01:04 AM 9/26/2001, mda_at_[hidden] wrote:

 >--- In boost_at_y..., Beman Dawes <bdawes_at_a...> wrote:
 >> At 06:20 PM 9/24/2001, mda_at_d... wrote:
 >>  >- boost/rational.hpp is self-contained; within it there is a
 >>  >namespace detail block (don't know why it isn't an anonymous
 >>  >namespace).
 >>
 >> It's good programming practice for header files never to put names
 >in the
 >> anonymous namespace, to prevent pollution of that namespace.
 >
 >is there just a single anonymous namespace? what happens with:
 >   namespace boost {namespace foobar {
 >   ...
 >   namespace {
 >   }
 >   ...
 >   }}
 >is that innermost namespace the same as a "top-level" anonymous
 >one? if so, then i guess i agree with you, though if that is how
 >C++ works, it seems like it kind of disables part of the point
 >of anonymous namespaces.

Each unnamed namespace acts as if it has a unique name made up by the 
compiler, and that name is the same for each use within the translation 
unit.  But nonetheless,  ::uniquename and ::boost::foobar::uniquename are 
different namespaces so there is no possible pollution issue.

I was a file scope unnamed namespace.

 >does anyone besides boost use "detail"? where did that come from?
 >why not "impl" or "priv"?

It is short for implementation_detail.  Perhaps it would have been better 
if we had used the more explicit name.  "impl" or "priv" would have been 
even less explicit that "detail".

 >are the semantics of "detail" to mean "don't go here" or is it
 >more like "advanced users only"?

I think of implementation details as more "read this if you want to, but be 
warned that it is an implementation detail which is not part of the public 
interface and may change unexpectedly."

 >> The source files need to be in a different directory hierarchy;
 >that's
 >> already been hashed out many times in the past.
 >
 >hmmm, ok. i think boost makes good points about the importance
 >of stating rationales; it'd be nice if these determinations were
 >stated on the web site with rational (or a url to a past
 >mailing list thread, if easier).

There is a paper on directory names by John Maddock with an addendum by 
Jens Maurer in the CVS.  Not very visible, however, and we aren't exactly 
follow either proposal, I think.

 >> So what happens if you apply those guidelines to the current
 >> libraries?  That's the proof of the pudding.
 >
 >there are many violations, some of which i listed.
 >that inconsistency is in fact what started me off in the first place.
 >current behavior is so inconsistent that it would
 >be difficult to state any meaningful guidelines that wouldn't conflict
 >with current libraries.

Sorry, I wasn't clear.  Try again:

If the current libraries noted in the examples were to be changed to meet 
the guidelines you suggested, exactly what would those changes be?  Would 
the changed libraries be better/just-different/worse from the current 
libraries from the standpoint of users/developers?

 >
 >> I'm not necessarily suggest we go back and change existing
 >libraries, but
 >> that we do make sure any new guidelines would have sense if they
 >had been
 >> originally applied when the libraries were initially developed.
 >
 >i wouldn't necessarily suggest retroactive cleanup on this either.
 >i also don't think the mandatory list of guidelines concerning
 >namespaces and subdirectories should be long.
 >there might be a longer list of optional conventions.
 >
 >also, i'm not just kvetching, i'm honestly curious what others
 >would suggest generally on this topic even if not applied to boost.
 >classes add another factor. for example, boost/pool/ is entirely
 >in a subdirectory, with no top-level header file, even though
 >it is in namespace boost -- because there is a "pool" class.
 >is that "ok"? maybe.
 >
 >i'm not prepared to posit a set of guidelines
 >i could defend; i'm just sure an improvement could be made over
 >current behavior. so maybe i should shut up :).

I agree with you that the current state is inconsistent.  And your posting 
has been helpful to illuminate some of the issues.

But to move forward we really would need someone to write a short set of 
guidelines (perhaps to become a part of the programming guidelines Dave 
Abrahams has worked on), and then patiently gather feedback from this list 
and try to reach consensus.

Part of the problem with these sorts of guidelines is that actual practice 
varies a great deal, and it takes a huge amount of discussion to get 
everyone on the same page and headed the same direction.  There is often 
personal preference involved, too.  We need to avoid trying to enforce 
political correctness, and we need to avoid damping inventiveness.  So 
guidelines are really, really, difficult.

--Beman