Comments and readable code

Comments, names, blank lines: code a person can read and change.

F1.5Programming basicsGCSE10 min

Covers OCR J277 2.3.1 Defensive design · AQA 8525 3.2.2 Programming concepts · Edexcel 1CP2 6.1.4 Readable code

Do this lesson in the simulator

Print it: worksheet (PDF) · answers (PDF) · as a web page

Programs are read far more often than they are written: by you next week, by a teammate, by whoever fixes the robot later. Code that is easy to read and change is called maintainable. This lesson is about writing it.

Comments

A line that starts with # is a comment. Python skips it completely. It is there for people.

# the two lines every program starts with: the commands, then the robot
from bugbot import *
connect()

# Flash the light so we know the program started
led("green")
wait(0.5)
led("off")

# Drive a short way
forward(50, distance=10)
print("done")  # a comment can sit at the end of a line too

Run this in the simulator

Run it: the comments change nothing. Now delete every comment and run again. Same behaviour, but the program says less about itself.

What a good comment says

A comment should say why, or what a group of lines is for. It should not repeat what the line obviously does.

led("red")          # set the LED to red        <- says nothing new
led("red")          # warn: battery is low      <- says why

Names that explain themselves

Lesson F1.6 gives values names. Before you get there, notice that a good name does the job of a comment:

wait(3)                  # what is 3?
wait(charge_time)        # the name says it

Blank lines and indentation

Python ignores blank lines. Use them to separate the steps of a program, the way paragraphs separate ideas:

# the two lines every program starts with: the commands, then the robot
from bugbot import *
connect()

# Step 1: announce
print("patrol starting")
led("green")

# Step 2: move
forward(50, distance=15)

# Step 3: report
print("patrol finished at", position())
led("off")

Run this in the simulator

Compare that with the same lines with no comments and no gaps. Both run identically; only one of them can be read at a glance. Spaces at the start of a line are different: Python does not ignore them, and module F2 is about why.

The patrol program as written, with comments and blank lines, and the five instructions Python runs from itwhat you writewhat Python runs# Step 1: announceprint(...)led(...)(blank line)# Step 2: moveforward(...)(blank line)# Step 3: reportprint(...)led(...)print(...)led(...)forward(...)print(...)led(...)comments andblank lines skipped
The same program twice. Python throws away the comments and the blank lines and runs the same five instructions either way. They are there only for the people reading it, to show the three steps.

Turning a line off

Putting # in front of a line is a quick way to switch it off without deleting it. Programmers do this all the time while testing:

# the two lines every program starts with: the commands, then the robot
from bugbot import *
connect()

print("before")
# forward(50, distance=20)
print("after")

Run this in the simulator

The robot did not move because the drive line is commented out. Remove the # and it comes back.

Task: a tidy drive

Write a program that turns the LED on, drives forward for a second, stops, turns the LED off and prints done. Put a comment above each part saying what it is for, and a blank line between the parts.

# the two lines every program starts with: the commands, then the robot
from bugbot import *
connect()

# ...

Challenges

  1. Take any program from an earlier lesson and add comments that explain why, not what.
  2. Comment out the stop() in a driving program. What stops the robot in the end?
  3. Write a program that is only comments. Does it run?

Past paper questions on this

Real exam questions that test this, each worked through with a program you can run.