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

From: Markus Werle (numerical.simulation_at_[hidden])
Date: 2007-01-08 09:48:17

Sebastian Redl <sebastian.redl <at> getdesigned.at> writes:

> 
> 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. 

... for the author

> If someone feels the need to reimplement a
> part of a Boost library, they might as well read and understand the code.

I have read Eric Niebler's splendid article 
http://www.artima.com/cppsource/foreach.html
Then I took a look at the bost implementation and could not find
any similarity at first glance. OTOH foreach.hpp is clean and cute code
compared to all the files that heavily rely on boost::preprocessor, which
nearly always is write-only code. See e.g. boost::fusion stuff or boost fusion
docs. "Effective boost::fusion" is yet to be written.

So I really appreciate the fact that Eric took the time to explain why he did it
and how, since the techiques he describes will save me one day. 
But it would be much better to have this article distributed as part of the
boost library as well, since I stumbled over Eric's article only by chance while
searching for something completely different.

Read and understand code like the stuff in boost::fusion where some
3-week discussion about compile-time complexity between the 4 best C++
programmers around the world is boiled down to the essentials and then
obfuscated with some macros is merely impossible.

I had big hope in the book from David and Aleksey
(http://www.aw-bc.com/catalog/academic/product/0,1144,0321227255,00.html), 
but it is way too short and gives not enough details.

OTOH I can really understand that it is hard work to get things boiled down for
the uneducated like me. 
This is why everyone kisses Scott Meyer's feet: he is able to EXPLAIN the what
and why - and he (or Addison-Wesley) gets a lot of money (from me) for this ...

> 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.
> 
> Thinking about it, I'm probably just arguing that such a manual should
> not be an external document ...

A detailed analysis and explanation of all BOOST_MACROS probably is
a step into a good direction ...

Markus