Re: [boost] [TTI] Review

Subject: Re: [boost] [TTI] Review
From: Gregory Crosswhite (gcross_at_[hidden])
Date: 2011-07-18 21:57:30

On 07/18/2011 05:41 PM, Edward Diener wrote:
>>
>> 2) I strongly think that "CREATE_METAFUNCTION_FOR" (or something
>> similar) should be inserted into all of the macro names because
>> otherwise they strike me as being misleading. If I were not familiar
>> with this library and I saw the macro BOOST_TTI_HAS_TYPE(X) in someone
>> else's code, I would be confused because the name of the macro makes it
>> sound like it is asking if X has some type even though the result
>> doesn't seem to be used. By contrast, if I saw the macro
>> BOOST_TTI_CREATE_METAFUNCTION_FOR_HAS_TYPE(X), it would be immediately
>> clear to me that the purpose of this macro is to create a metafunction.
>
> I can do that but I wonder if programmers really want to type that
> much <g>. I do not think they do even though I fully agree with you
> that your macro names are much clearer than the shorter ones.
>

Elsewhere in the discussion it was proposed that "GENERATE" be used so
that the macros would be called BOOST_TTI_GENERATE_HAS_TYPE etc, which
is much less verbose than my original suggestion.  I strongly support
this option, and believe that is very little additional typing for a
great deal of clarity.

And I just want to emphasize that without this change (or something like
it) the names of the macros are inherently confusing to anyone who
hasn't grown use to them because they make the macros sound like they
are doing one thing when they are actually doing another.  I don't have
a strong opinion about exactly how to fix this, but I do strongly
believe that this is a problem that needs to be fixed.

>>
>> I say this based in part on my own experience. When I was learning how
>> this library worked I started by skimming through the documentation to
>> get a feel for what was going on, and the macro names confused me
>> because I couldn't tell what they were actually doing. I did eventually
>> figure this out when I read through the documentation more closely, but
>> if they had names following the convention I am recommending then I
>> would have immediately understood what they were doing.
>>
>> Although my proposed change would require additional typing (though
>> unlikely not much, since I suspect most people are like me and just copy
>> and paste from a template), I think that the benefit of improving the
>> clarity would be well worth it.
>
> It is a decent suggestion but I do explain after all that the macro
> metafunctions create metafunctions for introspecting an inner element
> with a given name. 

Yes, but the less in-depth reading required to figure out something the
better for the person who eventually has to use your library ---
*especially* when they are in the position of unfamiliar reading code
written by someone else and so want to have to read as little as
possible from the documentation of the library to figure out what is
going on.

Cheers,
Greg