Re: [boost] usage of auto in tutorials

Subject: Re: [boost] usage of auto in tutorials
From: Joseph Van Riper (fleeb.fantastique_at_[hidden])
Date: 2019-03-20 09:43:32

>
> > Also, where does this end? Should tutorials stay away from
> > rang based for loops? Smart pointers? Templates? Namespaces?
> > C++ features all together?
> >
> > I know I'm exaggerating a bit, but I think it is a valid question.
> > From the perspective of a c programmer, all those things are "new".
> > However, outcome is a c++14 library so using c++14 features "where
> > they are usefull" should not be avoided, but embraced.
> >
> > Again, I'm not suggestion auto should be used everywhere, because it
> really
> > can decrease readability significantly, but imho example code (regardless
> > of
> > the context) should reflect current best practice and not based on
> > guesswork
> > about what language the users might be most familiar with.
> >
>
> I wonder what others in this group think? Maybe we could come up with some
> guidelines for documentation writers.
>
>
(I apologize for losing the attributions, but I wanted to keep focus).

I have a love-hate relationship with the 'auto' keyword.

For those times I find it difficult to work out the immediate type I should
use, copping out with 'auto' gets me to where I need to go, so I find it
'productive', in the sense that if I need to get something done and I can't
work through the maze of types that crop up occasionally, then I love it.
I especially love it when dealing with iterators and funky derived types
implied by who-knows-what consequences introduced through aggressive
templating without establishing typedefs to assist the poor sod stuck with
working out the type.  Or really terrible documentation that doesn't
explain that there is a typedef to assist you.

For those times when I really want to understand the code I'm using,
though, I despise it, because it simply hides that information away, and a
lazy developer can just use it without concern, never really understanding
what is happening, which I don't regard as helpful.

Also, I have run into production code using the auto keyword in ways that
created problems for us as the code shifted and changed.  The developer
used it to create the variables used within a for loop, and when the types
shifted (perhaps to use a different container, I forget the details now),
and the auto keyword resolved to a different type, it no longer worked
properly for some of the code within the for loop... probably because the
compiler had a choice of types it could resolve to, and chose poorly for
our needs.  Interestingly, had the developer used the actual type he
intended, the iterator he intended would have worked within the for loop
without issue.

So, yeah, I'm hot and cold about its use in production code, generally.
Useful when you need it, but can become a terrible crutch.

If I were to offer a guideline, I'd pick up on what someone else wrote in
this thread, and use it only after the type was clearly spelled out for
reader.  I'd use it within the same document, not buried in some other page
in some obscure area where the developer may have missed it because s/he
was focused on solving a specific issue and skipped most of the
documentation to focus on their specific issue.  That is, I'd take a cue
from journalists here, and treat it was you might treat an abbreviation,
since in C++ it sorta functions that way.  This way, you highlight that the
auto keyword exists in the language, you keep the documentation from
becoming needlessly wordy, yet still help show the reader what the type
should be so if they would prefer not to use auto, the documentation helps
them figure out what type they should use.  It also has the added benefit
of forcing the developer to consider the need for a typedef to keep the use
of their code from being too cumbersome (since if it's too wordy for
documentation, imagine what that's like for production).

- Trey