Variable names in tutorials

Seairth · 2017-08-27 16:13

I just read through the pong tutorial, which is also the first Blockly tutorial that I've read. One thing that caught my attention was the use of short, non-descriptive variable names. As a software engineer, I find that to be a generally poor practice, especially when teaching others to program. The variable should be descriptive enough to understand it's usage without having to consult any other code. All programmers (myself included, occasionally) eventually get lazy and start shortening our variable names, but that should not be how you start your programming career. Teach good programming practices, then let them go off and learn bad practices on their own.

Publison · 2017-08-27 16:16

Are you referring to this tutorial?

http://learn.parallax.com/tutorials/language/blocklyprop/capacitive-touch-pong-game

Seairth · 2017-08-27 16:26

That's the one.

Seairth · 2017-08-28 00:14

I feel I should also point out that there are excellent examples of good variable names in that tutorial, as well.

SRLM · 2017-08-28 01:56

Also, it's unfortunate that the choice of program representation is a PNG image. That won't search very well, either from Google or within the page.

SVG would be somewhat better: https://webmasters.stackexchange.com/questions/13848/do-search-engines-index-text-contained-in-svg-elements

Ken Gracey · 2017-08-28 19:29

Hey guys, this is valuable input for us to receive. Since we are using Blockly as a scaffold to text-based programming we need to use the most generally accepted programming naming conventions.

Can you be a bit more specific about which variable names you're referring to? Want snake case, camel case or something else? Please provide a few more specifics for us.

This particular tutorial was prepared by Carson, a 17-year-old intern who's headed to college in a few weeks.

@SRLM: will look at that next.

Thanks!

Ken

SRLM · 2017-08-29 03:46

It seems Chrome and Firefox have some gotcha behavior with regards to searching text in SVGs.

An SVG linked via an img tag is not searched: https://www.w3.org/TR/SVG2/text.html Although if you open the SVG in it's own tab, it's searchable.

However, if you embed the SVG directly in the host document, it is searchable (save page, replace img tag to experiment with this)

Related, if you generate the content dynamically it is also find in page-able, eg https://bl.ocks.org/mbostock/2565344

SRLM · 2017-08-29 03:49

For variable names, the ones that stick out to me are t, tT, sT, and x.

x might normally be ok in a graphics/math context, but since there is also a paddleX, it's a bit confusing.

Good variable names are important, especially since they're the main documentation in this code (does Blocky have comments?)

Minor note: the yellow arrow in this image http://learn.parallax.com/tutorials/language/blocklyprop/capacitive-touch-pong-game/calibration-and-programming seems to hang out a bit, without context. I would either add a matching note to the image, or in the caption add a note with something like "in the yellow text ..." and have the word yellow colored to match.

Seairth · 2017-08-29 15:02

SRLM wrote: »

For variable names, the ones that stick out to me are t, tT, sT, and x.

Yes, those were the ones that stuck out for me too (also, "s").

Variable names in tutorials

Comments