Comments and readable code

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

F1.5Programming basicsGCSE10 min

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.

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.

In the exam

Questions ask you to name ways of making code easier to maintain, and to explain why each helps. The four that come up are comments, meaningful names, indentation and white space, plus splitting code into subprograms.

OCR 2.3.1

OCR lists these under maintainability in defensive design: sub programs, naming conventions, indentation and commenting. In the Exam Reference Language a comment starts with two slashes:

// warn: battery is low

AQA 3.2.2

AQA asks you to use meaningful identifier names and to know why they matter: someone else, or you later, can understand what a value is without reading all the code around it.

Edexcel 6.1.4

Edexcel lists the techniques for readable code: comments, descriptive names, indentation and white space. The programs you write in Paper 2 are read by an examiner, so the same habits help them follow what your code does.

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

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