Phobos examples and auto

[torhu]

On 05.11.2011 20:49, Andrei Alexandrescu wrote:
> 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.

I probably wouldn't use auto in that case. I like having the type 
explicit, as it saves me from having to spend any effort on remembering 
what it was. Sometimes the type is too complicated, can vary, or is 
already mentioned on the right hand side of the expression.  Then often 
find myself using auto.

In short, I feel that in this example, auto takes away clarity without 
adding anything that makes it a net gain.