What is the correct use of auto?

[Robert Fraser]

Unknown W. Brackets wrote:
> Why?  I'm not sure I see the relevance of your analogies to the point.
> 
> Surely no one shall die if they use auto.  Also, not knowing what 
> something is (which can cause you no harm directly) is very different 
> from not knowing where incoming danger might be.
> 
> I think you're trying to say that having autos in examples is like 
> having mines, in that they are possible points of confusion to newcomers 
> (who will not know what those things are.)  You may also be trying to 
> say that using auto in examples teaches people to use auto more than 
> they should.
> 
> However, I would say that auto should not be used, except in any case 
> where the type auto is representing:
> 
>     - is unimportant to surrounding code (it is being paper-pushed.)

This is *NEVER* true in an example (unless the type being paper-pushed 
is from another API than the one being learned). Just because the 
example code never changes anything in the 
GodzillaAttackInitializationContext doesn't mean user code never will. 
If it's part of the API, its should be specified in the example.

>     - is unlikely to be used in any way other than the represented way 
> (e.g. has no other useful methods than are already being called.)

Again, only if it's not part of the API being demonstrated.

>     - is documented in some comment in the example.

I'd rather see the type in the code than in the comment, but this is OK, 
I guess.

>     - is an example type, with no actual importance to the example (e.g. 
> to be passed to a method that takes any value, which is what the example 
> is showing.)

OK, I'll give you that, as long as it's documented. A better way might 
be to show the same function working with two different (specified) types.

> 
> Here is an example which uses auto.  It is very simple and clear, and 
> auto is making the example better.
> 
> // How to write to stderr
> import std.stdio;
> 
> int main()
> {
>     // Most anything can be written using writefln().
>     // If it's an object, it needs a toString() method.
>     auto data = 42;
> 
>     // This outputs data (as a string) to stderr, and then a newline.
>     writefln(stderr, "Look at this: %s", data);
> 
>     // You can also use writeln() for unformatted data.
>     writefln(stderr, data);
> }

That example would better have been shown by having an int and printing 
it, then having a string and printing it, and showing how writefln works 
for both. And I would argue that in that case, the types are paramount, 
since you're showing how writefln works with any type.

> Also, anytime you have:
> 
> auto something = new Something();
> 
> It's reasonable to assume the reader of the example will understand what 
> something is, imho.  This is especially true with template examples, 
> where someone may (additionally) be overwhelmed by the extraneous 
> information in the declaration.

OK, that's fine. But method returns aren't, since you have to look up 
the method.

> -[Unknown]

Here's an example of a BAD example from Mango that frustrated the **** 
out of me about a year ago:

     void testServletEngine (Logger log)
     {
         log.info ("registering servlets");

         // construct a servlet-provider
         auto sp = new ServletProvider;

         // create a context for example servlets
         auto example = sp.addContext (new ServletContext ("/example"));

         // create a context for admin servlets
         auto admin = sp.addContext (new AdminContext (sp, "/admin"));

         // map echo requests to our echo servlet
         sp.addMapping ("/echo", sp.addServlet (new Echo, "echo", example));

         // point the default context to the tango help files
         sp.addContext (new ServletContext ("", "../doc/html"));

         // map all other requests to our file servlet
         sp.addMapping ("/", sp.addServlet (new FileServlet, "files"));

         // fire up a server
         testServer (sp, log);
     }

The second and third autos are the big problem here. They say "create a 
context for example servlets" and "create a context for admin servlets", 
but nowhere in the example is it shown what a "context" is, and the type 
"context" refers to is a mango.net.ServletContext. You wouldn't know the 
exact type without looking up ServletProvider.addContext. The servlet 
context is definitely something users would want to change, so while 
it's just paper-pushing in this example it is not in real-world code.

Also, from later in the same file:

     auto output = response.buffer;

 From it's name, my initial reaction would be some sort of char[] or 
ubyte[]. Then suddenly, it's written to using the whisper syntax. In 
retrospect, it makes sense that it's a tango.io.model.IBuffer (a class I 
didn't even know existed, and have no idea what capabilities it has), 
but this is the stuff I had to look up, since it's not clear from its use.

I think there was a much more annoying one there, but I can't seem to 
find it right now.