How not to do coding examples

As part of my MSc, I'm getting a few lessons in technologies I'm not familiar with. I've found some of these lessons extremely confusing - even when I'm proficient in the language.

Here's an example of a coding fragment from one of the tutorials in the R language. Let me explain everything that I think is wrong with it.

 Rbarplot(H, names.arg =M, col=“blue” xlab ='Country', ylab="Population")

something <- lm( mydata$Col1~mydata$Col2)

What are H and M? They are defined earlier in the document, but giving single character variable names is disrespectful to readers of the code. We aren't in the mainframe era where we have limited memory and have to use single characters. We're not being charged per word here!

There is no justification for single character variables. Even in toy examples like the above. Take the time to respect your readers' limited time.

Next - what's with the inconsistent spacing on the = symbol? Some languages are whitespace significant, others aren't. If you're a newbie to this language, do you automatically know whether R behaves weirdly if spaces aren't consistent?

Curly quotes! A sure sign that something has been written in a word processor which has "helpfully" turned a humble " into something more extravagant. Again, if you're new to coding, will you instinctively understand why the copy-and-pasted example has failed?

Why do some strings use single quotes and some use double quotes? Can " be replaced by two apostrophes - ''?

something is not a suitable variable name for anything. The lm() function creates a linear model. If this is the student's first time using linear models, are they going to remember what something is when halfway through the exercise? For tutorial code, it almost always makes sense to give variable names a hint of what they contain. For example, age_int lets the reader know what the variable represents and what it contains.

Again mydata is pretty meaningless. Is this the data I created or the data I loaded from the CSV? Sure, world_population_from_csv is a bit wordy - but it is unambiguous in the context of a lesson.

And on and on it went.

As I happens, I was the only person in our tutorial with experience of R. Lest you think I'm exaggerating, I had to deal with all of the above when trying to help my fellow students understand what was going on.

If you understand a programming language, you are almost guaranteed to write an unsuitable tutorial the first time around. You first need to put the examples in front of people unfamiliar with your language, paradigm, or even the basics of programming. Let them explain to you what they find confusing so that you can write a better tutorial.

Yes, that's harder work for you. But your job is to make learning easier for others.