Re: [boost] usage of auto in tutorials

Gesendet: Dienstag, 19. März 2019 um 16:49 Uhr Von: "Andrzej Krzemienski via Boost"

wt., 19 mar 2019 o 16:37 mike via Boost napisał(a):

...

...

-----Original Message----- From: Boost 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