From: Rob Stewart (stewart_at_[hidden])
Date: 2003-10-29 10:29:51
From: David Abrahams <dave_at_[hidden]>
> "Thorsten Ottosen" <nesotto_at_[hidden]> writes:
> >> By removing the rigor and formatting demands from the
> >> documentation, the library author can worry about the details of
> >> the code before its acceptance.
> > I see a great danger in this approach. I think that if you can't write the
> > right/satisfactory documentation
> > about your code, then the library might not be ready for a review. I
> > constantly find errors in my thinking and design when
> > I have to document it and explain why it is as it is.
> And very often, even if there are no technical errors in
> functionality, design errors are uncovered when you find that it's
> just too hard to explain. A design which is hard to explain is hard
> to use, and probably ought to be changed.
These are excellent points defending good documentation, but I
never said to skip good documentation. I suggested delaying the
"rigor and formatting demands" during the initial review.
-- Rob Stewart stewart_at_[hidden] Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk