Re: [boost] Re: string algorithms review

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;