The Consequential Detail (Ep. 12)
Can a single letter or one blank line make a difference? (Spoiler Alert: Yes)
I was interviewing candidates for coding instructor positions a few weeks ago. We ask candidates to teach for 20 minutes during the interview. But there's a catch. We're recruiting instructors to teach coding to children. So, we ask the candidates to pretend they're teaching 12-year-olds, even though all the panellists are adults. I'm now quite good at acting like a 12-year-old with no Python knowledge, despite my generally poor acting skills.
But I digress.
One of the candidates gave an example during the teaching demonstration that made me quickly reach for my notepad and scribble a reminder. This anecdote was perfect for an idea I was planning to write in Breaking the Rules. So, here we are!
It's the story of a single letter the candidate wrote on the screen.
In this post, I'll use coding examples. But don't run away… Don't worry if you're not familiar with coding. I'll explain what needs to be explained, and the key point in this post also applies to other types of technical writing.
A single letter • The candidate we were interviewing was required to introduce the for loop to the pretend class. A loop is a fundamental tool in coding that allows the computer program to repeat a number of lines of code several times. The candidate wrote this code on their screen:
bookshelf = [
"1984 by George Orwell",
"To Kill a Mockingbird by Harper Lee",
"Pride and Prejudice by Jane Austen",
]
for books in bookshelf:
print(books)The first section creates a list of books labelled bookshelf. It contains three books. The last two lines loop through this list and print out the name and author of the books, one at a time. The line that prints the book is repeated three times, once for each book.
It's not the most exciting computer program ever, but it'll do to demonstrate the for loop. The for loop statement—the line that starts with for—also introduces a new variable. This is a label used to refer to each of the books. The candidate used the variable name books for this.
Let's start with positive feedback. The candidate chose to frame this example within the context of a simple story—the books are on a bookshelf. This is better than a context-free example, such as :
nums = [1, 2, 3, 4, 5]
for n in nums:
print(n)This type of soulless example is fairly common in coding tutorials. Not in mine, though! I wrote about framing technical content within a story in earlier posts in Breaking the Rules. [Frame It (Ep.3) and Frame It • Part 2 (Ep. 9)]
So, what's the issue with the code the candidate wrote?
It's the letter "s" at the end of books. It should have been book. This won't affect the code. The program will still give the same output. But it will affect the learning process.
Here's why. The key concept we want a learner to grasp when learning the for loop is that you have something which contains several items, such as the bookshelf with several books, and you go through each one of those items one at a time and repeat the same action on each book.
The variable name we choose should describe this process. The code the interviewee wrote, which used books (plural) as the variable name, can be misleading. We want learners to understand that this name is equal to the first book the first time the loop runs, then the same label is used for the second book, and finally for the third one.
The correct label to convey this is the singular book, not the plural books. It's just one letter. It may seem an inconsequential detail, but not for a learner trying to visualise what's happening.
A blank line • Here is code I often use when teaching the for loop to children. This uses a module in Python that allows us to draw simple (and not-so-simple) shapes on the screen:
import turtle
fred = turtle.Turtle()
for side in range(4):
fred.forward(100)
fred.left(90)We're fetching the module, which is bizarrely called turtle, and we create "a turtle" which will move across the screen to draw lines. We call him fred (deliberately using a lowercase "f", in case you're thinking I forgot my English grammar.)
You'll spot another for loop. This is a bit different from the earlier one. It repeats the last two lines four times to create a square. The sides of the square are 100 pixels long.
Anyway, I then add the following line:
import turtle
fred = turtle.Turtle()
for side in range(4):
fred.forward(100)
fred.left(90)
fred.dot(10)This draws a single dot of radius 10 pixels on the last corner of the square. It only draws one dot because the line of code that draws a dot doesn't have an indent, and this is what Python needs to determine what is repeated and what isn't.
But some students used to think there's only one dot because of the blank line I left between the for loop and the line of code that draws the dot.
The blank line is there purely for display purposes. Blank lines in code are a bit like starting new paragraphs when writing. There's no fixed rule on when to use them. It depends on how you want to structure your code.
But beginners often think those blank lines affect the code. They don't
So, now I write this example without the blank line:
import turtle
fred = turtle.Turtle()
for side in range(4):
fred.forward(100)
fred.left(90)
fred.dot(10)For the beginner, it should be clearer that the only difference between the lines that are repeated four times and the one that only runs once is the indent, not the blank line.
A small, almost insignificant change—but one that can make a significant difference to a learner.
It's a small detail but a consequential one.
Afterword • As you may know, I experiment quite a bit with my technical writing in my other substack, The Python Coding Stack. Recently, I went a step further and wrote, if that's the right word, a picture story about a Python technical topic. Even if you're not into coding, you may enjoy parts of this picture story: Clearing The Deque—Tidying My Daughter's Soft Toys • A Python Picture Story.
