What is the correct use of auto?

[Unknown W. Brackets]

Surely; but I think cases where you have to deal with another API (e.g. 
of another library) are actually very frequent.  Documenting them in 
your documentation may neither be prudent nor helpful.

Most of the time, using auto for a return type is bad.  However, it 
might be good - especially with a comment like this:

// Version 1 and 2 return different types here.
// Version 1 returns "Xyz" and version 2 returns "Abc".

Or also:

// The type returned here may change at some point.
// It will always have a "runFromGodzilla" method, which is the only one
// that is useful in this version of the library.

And similar.  Undocumented, or poorly documented, examples are another 
problem.  Telling me that your car runs badly without gas doesn't mean 
tell me anything about oil.  Sure, they may both be things to improve 
with your car.

I didn't say my example was perfect, but it isn't a wrong or confusing 
use of auto.  If I were really documenting the use of stderr, I'd 
probably show mainly strings, much more in the way of formatting, etc. 
Likely I would also describe why and how it is best for error messages, 
even possibly a basic primer on how to pipe it properly.

Sorry I did not give a fully developed example.  It was merely to 
illustrate, since I'm sure anyone participating in this conversation 
understands stderr.

I frankly hate Mango/Tango's abuse of the (), and etc.  I think it makes 
for hard to read code, confuses beginners, and isn't even clean.  I 
realize many disagree and this is obviously a personal opinion.

But I think anyone would agree that isn't a good example and auto has 
been misused there out of laziness.  I just think that saying "auto is 
wrong always" is very likely incorrect.

-[Unknown]


Robert Fraser wrote:
> 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.