Re: [boost] Preprocessor: Nested loops

From: Paul Mensonides (pmenso57_at_[hidden])
Date: 2006-02-18 04:23:41

> -----Original Message-----
> From: boost-bounces_at_[hidden] 
> [mailto:boost-bounces_at_[hidden]] On Behalf Of David Abrahams

> > It is understandable, but nevertheless wrong in my opinion, that 
> > authors of documentation assume the reader will read the 
> whole thing, 
> > from the begin to the end, with devotion (and time). 
> Typically I have 
> > a concrete problem, and now just need the right tool to solve it.  
> > Thus I don't want to understand for example the whole Boost PP 
> > library, but I just want to create a double-nested loop with simple 
> > content (just as an example). Giving me general advice about good 
> > programming style and how to use the library in a good way, 
> not to use 
> > it for the wrong purposes, might at some time interest me, but this 
> > should go into some special section (actually, it would be good to 
> > have this general discussion for a library; but as I said, 
> I believe 
> > it should go to its own place, with appropriate links to it).
> 
> Several people (including me) have had this discussion with 
> Paul many times.  Although I disagree with him about this, I 
> respect Paul's point of view in the matter.  I suggest, 
> unless you can find some new angle to the argument, that 
> nothing new will come of repeating what others before you 
> have tried and failed at.

It isn't that I don't believe that this is a good thing; it is that I don't
believe that it is _possible_ without much more writing than those who ask for
it believe.  It would, for example, make the documentation for the pp-lib much
larger than all of the rest of the documentation for Boost combined.

I don't think that it is legitimate for users to expect to be able to have all
their problems solved by the library without putting some effort into learning
the language in which it is written.  The other side of the coin is that I don't
think it is legitimate for users to use some parts of the library without
putting in some effort to learn the conventions used by the library (the primary
one being how it handles recursion from a client interface point of view).  I
don't think, for example, that it is a long jump from "I tried to use
SEQ_FOR_EACH inside itself, and it didn't work" to the topical article about
reentrancy.

Most of the time I get these complaints, it is because the documentation doesn't
start with a particular user's problem and provide a direct (or near direct)
solution.  Even attempting to do that is like trying to produce a comprehensive
list of uses for looping constructs in programming language.

Then I get complaints that the examples are too contrived.  In essence, they
don't produce a reusable result (i.e. a use case).  Then I get complaints that
the examples are too complex.

I just don't think there is any way that I can win, and I get discouraged every
time I try because nothing is ever good enough.  Preprocessor metaprogramming
has an inherently steep learning curve.  I can't just make that disappear by
using better words.  No matter what I do, there will be someone who will
complain.  The root of such complaints is always (or nearly always) that I don't
somehow magically make the learning curve disappear.  That I don't provide some
kind of tutorial that takes a user from absolutely basic concepts to advanced
idioms--only with small progressive steps.  I don't think that's possible, and
if it is, I certainly don't know _how_ to do it (especially not without 500+
pages of prose).

> > A final word: I know it from myself (not regarding 
> documentation, but 
> > articles) that we tend to make a big fuss about our 
> products, how it 
> > relates to so much other things, and how much a proper 
> understanding 
> > of our product will help so much the reader. So we tend to obscure 
> > that actually what we are doing is quite simple --- and can be used 
> > quite simply.
> 
> For most people, the PP lib gives the illusion of being quite 
> simple and familiar, but then there are issues like this 
> recursion thing that you ran into, which don't map neatly 
> onto the ordinary programming paradigms we're used to.  I 
> think those phenomena are harder to explain simply.

That's true.  However...

1) The lack of recursion (or infinite replacement) in macro expansion is a
pretty fundamental concept that user's should already know *long* before they
start throwing preprocessor metaprogramming at a problem.  If the user doesn't
know that, than the user *probably* (and I'm not pointing a finger at you
Oliver) doesn't know the rest of C++ (including modern C++ idioms) well enough
to really know if preprocessor metaprogramming is necessary or better than the
alternatives.

Preprocessor metaprogramming is used mostly (by far) by people that have already
run smack into situations where it was necessary after exhausting all other
possibilities (i.e. they couldn't do it any other "good" way).  That is not to
say that the use of preprocessor metaprogramming should always be a last resort.
But, like anything else, it should be used only when it is "better" than all
other alternatives.  The problem is that it takes a significant degree of
familiarity with other alternatives (like templates and template
metaprogramming) to make that comparison--which is why the pp-lib docs don't shy
away from templates.

2) IMO, the "Reentrancy" article in the documentation does a pretty good job of
explaining the library's conventions in this regard.

Regards,
Paul Mensonides