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

From: Beman Dawes (bdawes_at_[hidden])
Date: 2001-09-25 10:44:11

At 06:20 PM 9/24/2001, mda_at_[hidden] wrote:

 >i'm having a hard time making any sense of what boost's
 >policy is supposed to be for boost developers (developers,
 >not users) for nesting namespaces within boost,
 >for using subdirectories, for use of the "boost/detail"
 >directory, etc. -- and how those policies might be related.
 >
 >some conflicting examples:
 >
 > ...
 >
 >- 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.

 > ...>
 >and those are just some samples. it is easier to find differences
 >than similarities.
 >
 >i imagine some people don't see this as a problem.
 >it probably doesn't bother boost users who will just examine
 >the top-level directory. but it does bother at least some people
 >(me for example :)) who want to get an understanding of the structure
 >by perusing the source tree.

The difficulty has been to find a set of guidelines that doesn't put 
developers in a straight jacket.  Past discussion were also hampered by 
lack of experience; we didn't have a lot of examples to look at.  Now we 
have more examples, so maybe it is a good time to reopen the discussion.

 >some sample guidelines might be:
 >
 >- if a file is defining symbols in namespace boost::foo:baz
 >it should be in directory boost/foo/baz/
 >
 >- vice-versa, code in a directory boost/foo/baz/ should be defining
 >symbols in namespace boost::foo::baz

Those guidelines always seems to be the starting point.

 >- an exception is that the "src" subdirectory may be used for
 >.cpp files implementing headers in its parent directory.

The source files need to be in a different directory hierarchy; that's 
already been hashed out many times in the past.

 >- the "detail" subdirectory is not an exception to these rules.
 >- an exception is that at top-level (only) a file boost/foo.hpp
 >may include files from directory boost/foo/, and those included
 >files may define symbols in namespace boost, not just namespace
 >boost::foo
 >- for purposes of these rules, class names are not reflected
 >in the directory hierarchy, and symbols such as in class
 >boost::myclass such as boost::myclass::mytypedef are still
 >defined in file boost/myclass.hpp.
 >
 >comments?

So what happens if you apply those guidelines to the current 
libraries?  That's the proof of the pudding.

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.

 >there are other things that bother me here too (that "pending"
 >directory which IMHO should be a peer to boost, not a subdirectory,
 >the occasional practice of using files by the same name in different
 >directories, etc.) but i'll stop for now.

What's the problem with "files by the same name in different 
directories"?  Some names like "Jamfile" are requirements of tools, others 
are just plain convenient.  As more and more libraries are added, keeping 
names totally unique is impractical.

It would be nice, however, to have a clearer set of guidelines for the 
header/namespace issues, if we can come up with one.

--Beman