Attention Course Instructors: Please Stop Reading Your Code

When watching online coding tutorials makes me want to light my computer on fire

If you couldn’t tell, this is code!

For the past six months, I’ve spent a lot of time getting up to speed with the latest in machine learning, deep learning, and natural language processing. There are a wealth of online resources in the form of blog posts, ebooks, research papers, and online videos. I wrote a whole post about ML-related cheat sheets you can find online. There is also a lot of mediocre (and crappy) content, which anyone that has used the web for more than a few minutes has seen.

The online course sites such as Udacity and Coursera have great options for instructor-led material on a variety of topics. I’ve watched several video tutorials and recordings of college classes on everything from Pandas and PyTorch to Backprop and Naive Bayes.

One thing I’ve come to cringe over is when an instructor opens up a Jupyter Notebook and starts talking about their code. Instead of describing the WHY of the code they wrote, most explain the WHAT. Instead of going through the thought process for using particular methods, values, and loops, they read code line-by-line.

It’s similar to speakers that read their slide presentations word-for-word. It’s not story time with my 2-year-old. I can read!

Consider this line:

learningRate = 0.001

The cardinal sin in my book is to say:

Here we set the learningRate variable to the value 0.001.

Yes, that’s correct. That is the audible translation for that line of code, which anyone that has ever done any programming understands implicitly.

WHY are we setting learningRate to 0.001? What’s special about 0.001? Why not 0.01? And it’s ok to say “there is a range of values I could have picked, but I decided on 0.001 because it’s a common starting point for learning rate.”

Maybe you don’t have a good reason for picking 0.001. That’s ok too! Programmers know that we make stuff up as we go. Each line isn’t about proving that you have all the answers. Programming is exploration.

If you are going through the trouble to talk about code, you have to do more than just read it line-by-line. If you aren’t going to explain it, then provide a link to your github repo and let them download it.

If you think are you over-explaining the code, you probably aren’t. The nice thing about the video/audible format is that there is less of a penalty for over-explaining compared to the written word.

Consider a simple line like this:

for _ in range(1000):

If you were writing out an explanation, you might not want to spend time covering the underscore character and how it is a throwaway variable. However, when you are talking through an explanation, it is easy to mention. But that’s not all! WHY are we using a throwaway variable in this case? Why not a named variable? Why does it not matter that we properly assign the current index of the range we are on during the loop? Why 1000 for the range?

Some may argue that comments in the code should provide enough explanation, but I’d debate that point too. If you want to simply give me a copy of your code so I can modify it for my purposes, comments in code are sufficient. However, if I’ve signed up for your course to learn something, you can assume I want you to error on the side of over-explaining all aspects of the code than just assuming I know your motivation for using the underscore variable.

Perhaps some programmers would complain that they don’t want everything explained to them at that level, which I can sympathize with as well. For online classes, you have to assume the lowest common denominator is pretty low. Perhaps courses should be better tagged as advanced when appropriate, and in those cases, you can skip the over-explaining every detail. That said, for anyone that has done pair programming, I’ve rarely been in a situation where someone spent too much time explaining their code. It almost always is the opposite. You think you are over-explaining when in reality you are providing just enough detail so the student can follow along.