08. Comments and notes to yourself

You met comments briefly in Chapter 07: text Python ignores when it runs the file. They let you leave notes for the most forgetful programmer you will ever work with — yourself, next week. Good comments turn a wall of code back into something you can read.

The two kinds of comment

A single-line comment starts with #. Everything from there to the end of the line is ignored:

# This whole line is a note for a human.
print("Hi")          # A note can also sit after some code.

For a multi-line block of notes, use several # lines in a row, or use a triple-quoted string (""" or '''). A triple-quoted string that is not assigned to anything is ignored by Python at runtime, making it useful as a comment block:

"""
This is a longer note. It can run for several lines.
Python ignores it because nothing uses the value.
"""
print("Still runs.")

Use single # lines for short notes and for commenting out single lines of code. Use """ blocks for a paragraph at the top of a file or any longer explanation.

Comment why, not what

The most common beginner mistake is comments that just repeat the code:

score = 0       # set score to 0
score = score + 10  # add 10 to score

Those comments add nothing — the code already says what it does. A useful comment explains why, or warns about something surprising:

score = 0       # players always start a round on zero
score = score + 10  # bonus for finishing under par

A good rule: if the comment and the code say the same thing, delete the comment. Save them for the why, the gotcha, and the not obvious.

Commenting out code

Comments have a second job: switching code off without deleting it — one of the most useful debugging tricks around.

Suppose a program misbehaves and you suspect one line. Put # in front of it and run again:

print("Step 1")
# print("Step 2")
print("Step 3")

Now "Step 2" never prints. If the problem goes away, you found your culprit. To switch the line back on, delete the # — faster and safer than deleting and retyping it later.

To switch off a whole block, put # in front of each line, or wrap it in a """ block:

"""
print("These three")
print("lines are")
print("all switched off")
"""
print("Only this line runs.")

A header for every file

A habit worth building: start each file with a short comment block saying what it is for. Future-you will thank present-you.

"""
Greeting program.
Asks for nothing; just prints a friendly welcome banner.
Written while learning Chapter 08.
"""

print("Welcome!")

Homework

Homework files are in exercises/08/homework/.

start
end

Stuck or finished? Open the homework solutions page.