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.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk