[boost] Re: Divergent Paths in Boost?

From: David Abrahams (dave_at_[hidden])
Date: 2003-11-03 16:34:37

Rob Stewart <stewart_at_[hidden]> writes:

> 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 

example?

> 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.

I haven't seen much (any) emphasis on implementation details during
reviews.  If there were much, I'd probably agree that discussion of
the details should be saved unless it had a major impact on
performance.

> 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.  

Please try to stick to objective terminology.  What's a "barrage"?
Getting a lot of feedback is valuable.

> 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.

What, then, are they about?

> 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.

Agreed.

> 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.)

The last example of extensive documentation discussion I remember had
the reviewee *requesting* detailed information from the group about
how to do a better job.

> 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.

If even that is inadequate to getting good documentation, then the
library shouldn't be accepted.

> 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.

I don't think anyone suggested that documentation should be "final".

> Reducing initial documentation requirements, 

>From where we already are ("reviewers can pick up the library for the
first time and understand its purpose, design, and use with little to
no hand holding") to what, exactly?  I don't think the requirements
you quoted are unneccessarily strict.

> with a secondary review once finalized,

And what if the documentation still isn't up to snuff.  Can we reject
it then?  How will that help?

> plus reducing the message traffic during the review

??  Are you serious?  You want to suppress review participation?  We
have a hard enough time getting people to take a serious look at a
library already.

> will alleviate the problems I see.
> 
> Once the code is stable, the documentation can be scrutinized.

That's not an acceptable approach as far as I'm concerned.  Once the
documentation is clear and complete enough to be scrutinized, the
code and design can be tweaked.  Without clear and complete
documentation, I can't even really begin a review.

> 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.

Doesn't work for me.  Without formal documentation I don't know what I
can expect a library to do, or how to evaluate whether its behavior is
buggy or not.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com