Phobos examples and auto

Manu turkeyman at gmail.com
Wed Nov 9 06:29:16 PST 2011


On 5 November 2011 22:14, Andrei Alexandrescu <SeeWebsiteForEmail at erdani.org
> wrote:

> On 11/5/11 3:02 PM, bearophile wrote:
>
>> Andrei Alexandrescu:
>>
>>  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.
>>>
>>
>> D programmers are probably able to learn to use auto later, because
>> it's handy, it's an attractor. On the other hand one of the main
>> purposes of the online documentation is to be as clear as possible. D
>> written by newbies is not the same D written by D experts. But
>> documentation must be written for D newbies too, because they are
>> ones that have more need of documentation. The code written in the
>> thousands of examples in the very good Pascal/Delphi docs was written
>> in a clear style that is not the same compact style an expert Delphi
>> programmer writes code. So I'd like D docs to avoid auto when the
>> types are not very clear. The purpose of the docs is not to shows
>> examples of idiomatic D code written by experts.
>>
>
> Patronizing one's reader is a common trap.


There's nothing patronising about printing the types clearly.

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.
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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20111109/d9198866/attachment-0001.html>


More information about the Digitalmars-d mailing list