<div class="gmail_quote">On 5 November 2011 22:14, Andrei Alexandrescu <span dir="ltr"><<a href="mailto:SeeWebsiteForEmail@erdani.org">SeeWebsiteForEmail@erdani.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="HOEnZb"><div class="h5">On 11/5/11 3:02 PM, bearophile wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Andrei Alexandrescu:<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
If we avoid "auto" in documentation examples but we do use it in<br>
everyday code, we effectively foster a style that's foreign and<br>
non-idiomatic to newcomers.<br>
<br>
Sample code should mimic real code. If real code would use auto,<br>
sample code should use auto.<br>
</blockquote>
<br>
D programmers are probably able to learn to use auto later, because<br>
it's handy, it's an attractor. On the other hand one of the main<br>
purposes of the online documentation is to be as clear as possible. D<br>
written by newbies is not the same D written by D experts. But<br>
documentation must be written for D newbies too, because they are<br>
ones that have more need of documentation. The code written in the<br>
thousands of examples in the very good Pascal/Delphi docs was written<br>
in a clear style that is not the same compact style an expert Delphi<br>
programmer writes code. So I'd like D docs to avoid auto when the<br>
types are not very clear. The purpose of the docs is not to shows<br>
examples of idiomatic D code written by experts.<br>
</blockquote>
<br></div></div>
Patronizing one's reader is a common trap.</blockquote><div><br></div><div>There's nothing patronising about printing the types clearly.</div><div><br></div><div>As a D new comer myself, I DEFINITELY want to see the types associated with function documentation in such examples. It re-enforces my memory, and also informs me if I don't know without wasting my time looking it up.</div>
<div>It might even be nice if that doc also hyperlinked to the type and function references themselves... save me more time looking this stuff up.</div></div>