How not to do coding examples
code MSc r · 6 comments · 100 words · read ~489 times.
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.
Well said.
I would say also that you shouldn't code like this either, definitely not if you're writing in a team
(In my very humble opinion)
See also foo, bar and baz
THIS!! For any tutorial, "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."
I should probably stop using i and j for for loops then?
@edent says:
For coding examples, you should use the think that the loop represents.
for (person in list_of_people) { ... }makes more sense for the new reader. If you're just using it as a counter, there's nothing wrong with saying something likecount = 0; while (count < 10) { count++; }David H says:
Teaching myself to code slowly again, I find myself reverting back to hand writing certain functions to commit to memory or reference later, regarding spacing I use a method I learned from a great Professor from my intro to c++ a long time ago, using a sub script delta symbol to denote spacing. That said I agree with much of your assessment, trying to juggle learning multiple languages starts to get syntactically overwhelming depending on the language(s). Tutorial wise, it would be great to see a tool for IDE's that adds comment context when you mouse hover over a section/selection of code, UI might be a challenge in terms of making it non intrusive, but you could add your own context as well, like a personal wiki with edu link/git links and contextual examples, and analogous examples that work for each individual.