Re: [boost] Re: Divergent Paths in Boost?

From: Rob Stewart (stewart_at_[hidden])
Date: 2003-11-03 13:31:44

From: David Abrahams <dave_at_[hidden]>
> "Paul A. Bristow" <boost_at_[hidden]> writes:
> 
> > | Every review of late seems harsher than the one before wrt
> > | documentation, for example.
> >
> > My impression too. And some emphasis on formal over useful, for
> > which examples are often most helpful.
> 
> Well, OK, at least two people think reviews are getting "harsh".  What
> sorts of things make a review harsh, and can the review manager do
> anything to make sure the atmosphere is "kinder and gentler?"  We
> have to be sure not to suppress legitimate technical argument.

Technical questions and alternatives generally warrant complete
discussion during a review.  Careful wording is all that's needed
and there usually isn't much problem with that.  However, some
technical discussions relate mostly to alternative implementation
ideas which don't change interfaces or invariants and should be
saved until after the review.  That means there's less of a
barrage during the review for the submitter to handle.

Naming is important to discuss -- ad nauseum at times <grin> --
during a review, so long as things remain civil, since names can
be so important to clarity.

What I find harsh, lately anyway, is the barrage the submitter is
subjected to during such a short time.  Many of the messages, or
a fair portion of many of the messages *seem* to be about things
unimportant to whether the library is a good idea, is well
conceived, is well implemented, and is sufficiently documented.

The criteria for the initial documentation is whether reviewers
can pick up the library for the first time and understand its
purpose, design, and use with little to no hand holding.  If a
reviewer can't understand a library, then the submitter might be
able to clarify something.  The worse the documentation, the less
likely any reviewer is to participate, so the more likely a
library will be rejected out of hand.  Such discussion is
warranted during the review.

Suggestions and corrections to the documentation would be fine.
However, any further discussion of those suggestions, or other
documentation comments should be deflected for another time to
reduce noise during the review.  (If not postponed, at least the
subject should change from "Re: Foo Review" to something more
specific.)

A lot of time can be spent on documentation and, depending upon
one's facility with English, precondition/postcondition
specification, etc., it may prove woefully inadequate anyway.
What's worse is that signatures, names, even whole portions of a
design can be changed because of the review, so the documentation
effort could well be wasted.  It's too much to ask that a
submitter produce final documentation prior to such a review.

Reducing initial documentation requirements, with a secondary
review once finalized, plus reducing the message traffic during
the review will alleviate the problems I see.

Once the code is stable, the documentation can be scrutinized.
When applicable, and the library is good enough, the
documentation can be formalized, if it wasn't previously, to make
it ready for the LWG.  Anything that happens earlier than I've
outlined is icing on the cake.

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