1 - Start: Code Someone Else Has to Read ~4 mins
You will read a short working Python program that scores GAA matches, and you will meet it exactly as a stranger would: named with single letters, no comments, nothing to tell you what it does.
Then you will document it, giving the names real meaning and adding comments, until another person could pick it up and follow it. Documentation is the skill today, not new code.
This lesson reads and improves one program in place. Students do not build a new program from scratch, so head off the expectation that they will be typing lots of fresh code.
The point to land: the computer runs the program the same whether the names are t or total_points. Documentation is entirely for the human who reads it next, and that human is often you in three weeks.
2 - Read the Mystery Program ~8 mins
Read it, but do not run it yet. Predict what it prints for the two matches listed, then work out what a, b and t each stand for. This is deliberately hard to read, that is the whole point.
Now run it and check your prediction against the output.
def s(a, b):
t = a * 3 + b
return t
m1 = s(2, 8)
m2 = s(1, 15)
print(m1)
print(m2)Predict first, before anyone clicks Run: what will this program print? The right answer is 14 then 18, because a GAA goal is 3 points (a * 3) plus the points (b): 2 goals 8 points is 14, 1 goal 15 points is 18.
The common wrong prediction is that students cannot tell at all, or guess a and b are the wrong way round. That confusion is the lesson: the code works, but nobody can tell what it means. Ask groups of two to agree what each letter stands for before you reveal it.
3 - Give the Names Meaning ~8 mins
The fastest way to document code is to rename things so they explain themselves. Rewrite the program with real names: score_match for the function, goals and points for what goes in, total for the result, and match1 and match2 for the two matches.
Type this over your program, then run it. The output is exactly the same, 14 then 18, because renaming changes nothing the computer does. It only changes what a reader understands.
def score_match(goals, points):
total = goals * 3 + points
return total
match1 = score_match(2, 8)
match2 = score_match(1, 15)
print(match1)
print(match2)Watch for students who think renaming will break the program or change the answer. Run it beside the old version if that helps: identical output, far clearer code.
A good name is the cheapest documentation there is. Say it, because clear names do more work than comments and never go out of date.
4 - Add Comments That Earn Their Place ~8 mins
Comment the why, not the what. Do not comment the obvious: print(match1) # prints match1 is noise.
Now add comments. A comment starts with # and Python ignores it, so it is there purely for the reader. Add a comment above the function saying what it does, and one on the tricky line explaining why goals are multiplied by 3.
Run it to confirm the comments changed nothing about how it works.
# Work out a GAA match score in total points.
# A goal is worth 3 points, a point is worth 1.
def score_match(goals, points):
total = goals * 3 + points # 3 points per goal, plus the points
return total
match1 = score_match(2, 8)
match2 = score_match(1, 15)
print(match1)
print(match2)Predict before running: will adding comments change the output? No, Python ignores everything after #. Some students expect an error or a change; confirm the output is still 14 then 18.
The habit to teach: comment the reasoning a reader could not guess, not the mechanics they can already see. Point at print(match1) # prints match1 as the classic useless comment.
5 - Your Turn ~6 mins
Open one of your own earlier Python programs and document it the same way. If it is missing from the shared device, ask your teacher or quickly retype a short one you remember.
Done looks like:
- Every single-letter or vague name replaced with one that says what it holds.
- One comment at the top saying what the program does.
- One comment on the trickiest line explaining why, not what.
- The program still runs and gives the same result as before.
Put students in pairs so each reads the other's documented program and says whether they could follow it cold. That read-back is the real test of documentation.
Differentiation: a student with no earlier program can document the match-scoring program further, for example adding a comment explaining what the two numbers passed in mean. Stretch: ask them to add a comment naming the goals-and-points rule for a reader who does not follow GAA.
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.