1 - Start: What We're Building ~4 mins
You are going to take a short, working micro:bit Python program that is hard to read and turn it into one anyone could follow. You will rename its unclear variables, add a comment that says what it does, and split a tricky line into clear steps. Same behaviour, far clearer code.
This lesson is about documentation as a skill, not about changing what a program does. Make it clear from the start: the program keeps working exactly the same, only the reading of it changes. That is the whole point of LO 3.6.
Documentation is a message you leave for the next person, and the next person is usually you in two weeks.
2 - What Documentation Means ~3 mins
Documentation is anything in a program that helps a human understand it. Two things do most of the work: clear names (a variable called score beats one called x) and comments, lines starting with # that Python ignores but people read. Good documentation does not change what a program does. It changes who can read it.
Head off the common belief that comments are a mark scheme box to tick. A comment that just repeats the code (# add one to score above score += 1) is noise. A comment that says why is documentation.
3 - Open the Editor and Type the Messy Program ~4 mins
Go to python.microbit.org. Clear whatever is there and type the program below exactly. It counts button-A presses and scrolls the count. Read it first: can you tell what a, b and c are for? Click Send to micro:bit or run the simulator to prove it works.
from microbit import *
a = 0
b = 0
while True:
if button_a.is_pressed():
a = a + 1
display.scroll(a)
sleep(300)
if button_b.is_pressed():
display.scroll(a)Predict first, before anyone clicks Run: what does button A do and what does button B do? Right answer: A adds one and shows the running count, B just shows the current count. Common wrong prediction: that B resets the count. Nothing here resets it, and that is a readability problem the names hide.
4 - Rename the Unclear Variables ~5 mins
The name a tells you nothing. It is a count of presses, so call it presses. The variable b is never used, so delete it. Change every a to presses.
Your program should now read like the one below. Run it: it behaves exactly the same, but you can read it now.
from microbit import *
presses = 0
while True:
if button_a.is_pressed():
presses = presses + 1
display.scroll(presses)
sleep(300)
if button_b.is_pressed():
display.scroll(presses)Watch for pupils who rename the display line but miss it inside the if button_b block, or the other way round. A single missed a will now be an error, because the name no longer exists. That is a good thing to point out: clear names make missed edits fail loudly instead of silently.
5 - Add a Comment That Says What It Does ~4 mins
Add a single comment at the top, under the import line, saying what the whole program is for. Write why it exists, not what each line does. Add it exactly where shown below, then run it once more to prove a comment changes nothing about how it works.
from microbit import *
# Counts how many times button A is pressed and shows the total.
# Button B shows the current total without adding to it.
presses = 0
while True:
if button_a.is_pressed():
presses = presses + 1
display.scroll(presses)
sleep(300)
if button_b.is_pressed():
display.scroll(presses)Some pupils will want a comment on every line. Steer them: a comment earns its place when the code alone would not make it obvious. The second comment line matters most, because it tells the reader button B does not reset the count, which the code alone does not make clear.
Unlock the full learning experience
You're previewing this lesson. Get full access to this lesson and hundreds more — each one ready to teach, with interactive activities, printable resources and pupil progress tracking built in.
This lesson is copyright of Coding Ireland 2017 - 2025. Unauthorised use, copying or distribution is not allowed.