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

From: Beman Dawes (bdawes_at_[hidden])
Date: 2003-11-03 21:15:37

At 04:34 PM 11/3/2003, David Abrahams wrote:

 >Rob Stewart <stewart_at_[hidden]> writes:
 >...
 >
 >> 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.

I agree with Dave 100%.

I've seen too many [non-boost] libraries that looked good until formal 
documentation was attempted, and then were found to have serious conceptual 
flaws requiring total rework or even abandonment. Or worse yet, formal 
documentation was never attempted, and the conceptual flaws only surfaced 
after users had wasted much time and money.

--Beman