-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Sebastian Redl Sent: 07 January 2007 18:17 To: boost@lists.boost.org Subject: Re: [boost] [documentation]Need for "programmar's guide" or "tech notes"
Larry Evans wrote:
A "programmer's manual" describing, at least briefly, the implementation, would help future redesigners find their way and avoid the pain of reinventing yet another wheel. This was called "technical notes" before:
I disagree. Such a manual would be a possibly considerable additional effort with minimal returns. If someone feels the need to reimplement a part of a Boost library, they might as well read and understand the code.
However, better comments in the code that explain the confusing parts (and the Boost libraries contain lots of confusing and roundabout code) would be generally a good idea, simply for future code maintenance and debugging.
I agree with this - as a reader of the often rather subtle Boost code (often obfuscated by portability constraints), I think there is a generally sub-optimal level of comments. Perhaps reviewers can note things that could benefit from more comments? Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com