Re: [boost] Re: algorithms namespace

From: Rob Stewart (stewart_at_[hidden])
Date: 2004-02-25 18:12:48

From: David Abrahams <dave_at_[hidden]>
> "Peter Dimov" <pdimov_at_[hidden]> writes:
> > Powell, Gary wrote:
> >> For me it's a matter of future expansion, and maintenance, we have
> >> boost::bind, and boost::lambda::bind, and perhaps soon
> >> boost:fcpp::lambda which is the namespace which the function? If we
> >> use apprev. 4 everythg, thn, we lose contx.
> >
> > No we do not. The abbrv anlgy is flwd. It's more like English::this
> > English::kind English::of English::writing versus en::this en::alternative
> > en::style.
> 
> Believe it or not the latter caused me a bigger mental hiccup.

They both hindered reading the text.  Upon seeing
"English::this," I had to consider whether "::" was a typo for ":
" or a namespace qualification on "this."  Since the former was
more likely than the latter, even given the context, I was
expecting the former.  When I saw "English::kind," it became
apparent that I needed to *ignore* "English::" and just read the
unqualified words.  Thus, when I got to "en::this," it was only a
momentary hiccup to note that "en::" was equivalent to
"English::" and continue reading by *ignoring* the "en::" part.

I emphasized the word "ignore" in the foregoing because that's
what I do when reading qualified code.  I skip over the line
noise to find the important information.  Only when things go
awry do I pay attention to the qualifications to get the extra
information.  That is why I prefer shorter namespace names: they
reduce the line noise.

An abbreviation should be as short as possible, but no shorter,
to turn a phrase.  My point is that making a namespace name too
short increases the chance of it being incomprehensible to many
and suggestive of other long names.  The case was already made
for "fs" possibly meaning things like "File System," "Financial
Services," "Fabulous Sockets," or whatever.  Note, however, that
in this case, "fs" is well established as an abbreviation for
"filesystem" and could easily pass the too short filter.  (Those
other libraries would need longer namespaces.)

Thus, choosing a good namespace name means to keep it as short as
possible without losing uniqueness and clarity, considering its
frequency of use.  The more often a namespace name will be used
in real code, the shorter it should be.

"algo" is a common abbreviation, in my experience for "algorithm"
and is much easier to spell (not to mention type)!  That makes it
a good alternative, but "fs" is a good abbreviation for
"filesystem," but "file" or "files" would work just as well.
Each library has to be handled case by case.

When reviewing a library, one can comment on the namespace name
as well as anything else.  That could even be made a specific
point to consider during a review.  That way, you get various
opinions and suggestions and the library author can make the
final determination.  They won't all be entirely consistent,
since each library author gets to choose, but hopefully a
groundswell of support for a namespace name contrary to the
author's preference will sway his/her opinion.

If Boost chooses to change a namespace name, the old name can be
retained, via namespace alias, for a few versions, marking it
deprecated upon the introduction of the new name.  That makes the
transition to a "better" name easier.

-- 
Rob Stewart                           stewart_at_[hidden]
Software Engineer                     http://www.sig.com
Susquehanna International Group, LLP  using std::disclaimer;