Re: [boost] usage of auto in tutorials

Subject: Re: [boost] usage of auto in tutorials
From: Mike (mike.dev_at_[hidden])
Date: 2019-03-19 18:18:24

> Gesendet: Dienstag, 19. März 2019 um 16:49 Uhr
> Von: "Andrzej Krzemienski via Boost" <boost_at_[hidden]>
>
> wt., 19 mar 2019 o 16:37 mike via Boost <boost_at_[hidden]> napisał(a):
> 
> > > -----Original Message-----
> > > From: Boost <boost-bounces_at_[hidden]> On Behalf Of Stephan Menzel
> > via Boost
> >
> > My personal rule of thumb for tutorial and demos is similar to how
> > you handle abbreviations in written text:
> >
> > First time you e.g. use a function, you explicitly show what the
> > function returns. Afterwards I use auto where it makes sense
> > (And yes, I know there are conflicting opinions about
> > "where it makes sense").
> >
> > With respect to the specific examples:
> > - Trailing return types in function declarations:
> >   If the style guide doesn't say something different, I only use
> >   them for very long type names and when they are needed.
> >   None of this applies here, so I don't see the benefit,
> >   but also not any harm. I'd say it is personal/project preference.
> > - The auto inside the if:
> >   The return type of the function is shown just two lines above.
> >   Again, personal opinion, but I'd claim it even increases
> >   readability, because it is less visual noise.
> >
> >
> > \rant on
> >
> > > [...]
> > >
> > > But for some people this looks very unusual. For example, because they
> > are
> > > not aware of this new syntax or they have not applied it and still write
> > > functions the old fashioned way.
> >
> > As I wrote, I rarely use trailing return types and I'm generally
> > no advocate of using auto everywhere, but this "new" syntax has
> > been valid c++ for more than half a decade now. If a professional
> > c++ programmer is still unfamiliar with this, then maybe more
> > exposure to it is actually a good thing and if boost doesn't spread
> > the word who does?
> >
> 
> There two sides to it. Yes, it is good to highlight new language features,
> and how they can be used.

Thats just it: auto is NOT a new language feature. Certainly not in the
context of a project that uses a c++14 library like outcome. 

> But it may conflict with the objectives of a tutorial, especially the
> initial page: the potential user should get the picture how (s)he will be
> using the library, as fast as possible. 

Absolutely, but who is to say that isn't just how most users will use the
library?

> This may be the matter of seconds.
> If we put off the potential user too much in this step, (s)he is likely to
> drop our library and go to the competition or go to manually write a
> similar (but lower quality) tool because determining whether our library
> does what is needed took too long.

To repeat my position: 
If you think that a particular use of [language feature X] 
is confusing for potential users and there is an alternative 
solution that is less confusing and results in a similar amount 
of code then sure, use that. 

All I'm saying is that I don't agree with the premisis of 
"Any feature that was not in C++98/C90 is automatically more
confusing for the "average" user". I can write absolutely 
confusing code in c++98 (and many boost libraries do just
that internally) just as easily as in c++17.

Maybe I'm biased, because I'm mainly working with people who
haven't already spent decades writing C or or C with classes and 
just now have to adopt to "new" c++11 features.
On the contrary: By now I believe I've written significantly more 
c++11/14/17 code than c++98. 
So I my experience might not be representative, but I don't think
it is an exception either. 

> > 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.

Me too, I'm only voicing a single (probably biased) opinion here. 
Thats not something you want to base your decision on.

> 
> Regards,
> &rzej;
> 
> 
> > Don't be afraid of change.
> >
> > \ rant off
> >
> > Mike
> >
> >
> > _______________________________________________
> > Unsubscribe & other changes:
> > http://lists.boost.org/mailman/listinfo.cgi/boost
> >
> 
> _______________________________________________
> Unsubscribe & other changes: 
> http://lists.boost.org/mailman/listinfo.cgi/boost
>