Re: [boost] [documentation]Need for "programmar's guide" or "tech notes"

From: Paul A Bristow (pbristow_at_[hidden])
Date: 2007-01-08 10:10:58

>-----Original Message-----
>From: boost-bounces_at_[hidden] 
>[mailto:boost-bounces_at_[hidden]] On Behalf Of Sebastian Redl
>Sent: 07 January 2007 18:17
>To: boost_at_[hidden]
>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
[phone] & SMS, Mobile [phone] & SMS
pbristow_at_[hidden]