Phobos examples and auto

[Andrei Alexandrescu]

On 11/5/11 1:48 PM, Walter Bright wrote:
> On 11/5/2011 10:42 AM, Steve Teale wrote:
>> There's a growing tendency in Phobos documentation to use auto.
>>
>> auto now = Clock.currTime();
>>
>> Now I can understand that when the RHS is some obscure template, whose
>> type might not be immediately obvious, the user should possibly be
>> encouraged to RTFM. But if the outcome is deterministic I just have the
>> feeling that documentation should provide information rather than hiding
>> it.
>>
>> OK, in Jonathan's example, this is preceded by a sentence that says that
>> the result is a SysTime. But the auto made me forget, and wonder what it
>> was, rather than reinforcing the preceding sentence.
>>
>> I realize that this is probably a trivial point, but at the same time, in
>> documentation, clarity is wonderful.
>
> I agree.

It's tricky. One simple fact that's been verified again and again is 
that documentation examples tend to be used a lot. They effectively are 
powerful style influencers for people learning the language.

If we avoid "auto" in documentation examples but we do use it in 
everyday code, we effectively foster a style that's foreign and 
non-idiomatic to newcomers.

Sample code should mimic real code. If real code would use auto, sample 
code should use auto.


Andrei