Re: [boost] [lib maintainers] Pleaseidentifyheadersinboost-root/boost

From: Robert Ramey (ramey_at_[hidden])
Date: 2007-11-18 11:48:38

Joel de Guzman wrote:

> No, of course not. But was has boost/shared_ptr got to do with this?

wow - this is the iconic example of a violation of "standard practice"

The file is implemented in boost/shared_ptr.hpp and shared_ptr
class is to be found in namespace boost.  This is not what
one would expect to find given that the documentation is
smart_pointers ...

>>>> The serialization library was reviewed TWICE and no one ever
>>>> mentioned this.
>>
>>> It's unfortunate that this has gone unnoticed from 2 reviews.
>>> Perhaps it didn't matter much at the time, or simply it slipped
>>> from the radar screen. Nevertheless, that does not make it right.
>>
>> I doubt it went unnoticed.  I suspect that it was percieved as
>> the "standard practice" at the time.
>
> It went unnoticed at least for me. I would have objected otherwise.
>
>>>> So rather than saying that authors have refused to follow "standard
>>>> practice", it would be more accurate to say that there has been
>>>> no definition of "standard practice" and many authors have
>>>> interpreted it in the most logical way given the current situation.
>>
>>> Agreed. I'm not quite sure about the "most logical" way though.
>>> For me, it's pretty clear that free-for-all addition of just about
>>> anything in the boost root directory and the boost namespace
>>> is not good. There are namespaces and subdirectories.
>>
>> As I said, I don't object to establishing a "standard practice".
>> But it's really annoying to be characterised as being unwilling
>> to respect a "standard practice" when no such thing has
>> been established.
>
> I don't think anyone is pinpointing you as unwilling to respect
> "standard practice".

> Yes, because boost/detail is not public API and the
> stuff there is implementation detail.

Hmm - and implementation details shouldn't be documented?
shouldn't be tested? If they're in a common area it seems
that they are meant to be used by more than one library -
and indeed they are. lightweight test others come to mind.

Its even worse.  Someone uses an "implementation detail"
from this public area. and the author decides to make
an interface breaking change.  This breaks a lot of stuff
and the author says - what's the problem? its and implemenation
detail.

Another case of ill defined "standard practice" creating problems.

>> Now I see that boost/utility/multi-pass has a documentation
>> page but no way to get to by following the links in the documentation
>
> I'm lost again. boost/utility/multi-pass is non-existent.

There is libs/utility/Mult-PassIterator.html  that isn't linked to anything.
I jumped to the conclusion that corresponded to a corresponding
module in boost/utility - sorry.  I'm not sure what "standard
practice" would indicate should be done with this - if anything.

>> index.  Then there is utility.hpp which is a convenience header
>> for a group of otherwise separate library - not including
>> mult-index.
>
> If a particular utility is useful for many libraries, then one of
> the libraries can host it prior to it getting reviewed independently
> and becoming a full-fledged boost citizen. That's the policy that
> we've been following with the synergy between xpressive and spirit,

I faced exactly that same issue with headers such as static_warning.hpp
There was already a header in boost/static_assert.hpp.  I thought
(and still think) that logical place for static_warning.hpp was in that
same directory.  I considered the possibility of placing it in
boost/serialization/static_warning.hpp but at the time I thought
I might have to change it later to boost/static_warning.hpp sometime
in the near future and I wanted to avoid an interface breaking change.

> for example. Case in point: fusion, proto, multi_pass, and many more
> smaller utilities and stuff. fusion was hosted by spirit before it
> was reviewed and was used by xpressive even before spirit did. Now
> that fusion passed the boost review, it has become a full-fledged
> boost citizen.

hmmm - I looked for it in boost on the trunk and 1.34 and didn't
find either documentation for it nor code.  I don't doubt its in
there somewhere but I can't find it.  Wouldn't "standard
practice" suggest that I look in boost/utility or perhaps
boost/iterators ? Hmmm has is been separately reviewed.

All these examples demonstrate that there really is
no defined "standard practice" and never has been.

Robert Ramey