Comments, and What the Computer Ignores

Part I · Module 1 · Chapter 1.9 · Comments, and What the Computer Ignores

1. The Mechanism

A # tells Python to ignore the rest of that line.

# This line is a note. Python skips it entirely.
print("Simulation complete")

Simulation complete

The comment produced nothing. Python read the line, saw the #, and moved on.

A comment can also follow code on the same line. Everything before the # runs normally; everything after it is ignored:

print("Simulation complete")   # this part is a note

Simulation complete

That is the entire mechanism. There is no closing marker and no multi-line comment syntax — a # affects one line, and a block of notes is several lines each starting with #.

# Three lines of notes.
# Each one needs its own hash.
# Python skips all three.
print("Simulation complete")

2. Comments Cost Nothing and Do Nothing

Two things beginners sometimes assume, both wrong:

Comments do not slow your program down. They are discarded when your file is compiled — Chapter 1.4, stage 2 — and never reach the running program at all. Write as many as are useful.

Comments cannot make your program work. A comment explaining what a line should do has no influence whatsoever on what it does. If the code is wrong, a confident comment above it just means two things are now wrong.

3. The Comment That Is Worse Than Nothing

Here is the style most tutorials teach, and it is a bad habit:

# Print the message
print("Simulation complete")

Read it honestly. The comment tells you the line prints a message. The line already said print. The comment added nothing, and now there are two lines to keep in step instead of one.

That last part is the real cost. Change the code and forget the comment, and you get this:

# Print the message
print("Compile failed")

The reader now has to decide which of the two to believe. A wrong comment is worse than no comment, and every restating comment is a wrong comment waiting to happen.

4. The Comment That Earns Its Place

Useful comments record something the code cannot say for itself. Almost always, that is why.

# This environment reports failures at ERROR severity, not FATAL.
print("Looking for: ERROR")

Now the comment is carrying real information. Someone reading the file six months from now can see that it looks for ERROR from the code. What they cannot see is that this was a deliberate choice about a specific environment rather than an oversight — and that is precisely what would otherwise get "fixed" by a well-meaning colleague.

Things worth a comment:

• Why a decision was made, especially a surprising one.
• A constraint from outside the code — a tool's behaviour, a file format, a convention someone else owns.
• A known limitation, so the next reader does not spend an hour rediscovering it.
• The intent of a section, when a file is long enough that the shape is not obvious.

Things not worth a comment:

• What an obvious line does.
• A translation of the code into English.
• Decoration, banners, and rows of hashes to separate sections.

5. Switching a Line Off

The second use of #, and one you will reach for constantly.

Putting a # in front of a working line stops it running without deleting it:

print("Compile")
# print("Simulate")
print("Report")

Compile
Report

The Simulate line is still in the file — you can put it back by removing one character — but Python skipped it.

This is genuinely useful when something is not behaving and you want to narrow down which line is responsible. Switch lines off until the problem disappears, and the last one you switched off is involved.

6. Predict, Run, Observe

Write down the exact output you expect before running this:

# print("one")
print("two")   # print("three")
print("four")

Then run it.

two
four

Two things to check your reasoning against. Line 1 was entirely a comment, so it did nothing. On line 2, the code before the # ran and everything after it — including something that looks exactly like a working print — was ignored.

That second one is the point of the exercise. A # does not care what follows it.

7. Exercise

Exercise 1 — improve a bad comment. Here is a restating comment:

# Print the error count
print("Errors:", 0)

Rewrite the comment so it records something a reader could not get from the code. You will have to invent a plausible reason — that invention is the exercise.

Exercise 2 — predict with a trap. Predict the output, then run it:

print("start")
# print("middle")
print("end")   # print("also ignored")

Exercise 3 — narrow down a problem. Write a file with four print lines. Switch off two of them with #, predict what remains, then run. Then put them back. This is the debugging loop in miniature.

Exercise 4 — judgement. For each, decide comment or no comment, and say why in a few words: (a) a line that prints a heading; (b) a line that looks wrong but is deliberately that way; (c) a line whose number came from a tool's documentation; (d) a line you copied and do not fully understand.

(For (d): the honest answer is that a comment is not the fix. Understanding it is.)

8. Summary

• # makes Python ignore the rest of the line. One hash per line; there is no multi-line comment syntax.
• A comment can follow code on the same line — the code before it still runs.
• Comments cost nothing at runtime and cannot change what the program does.
• Do not restate the code. A comment repeating an obvious line adds nothing and becomes wrong the moment the code changes.
• Record why, not what — decisions, outside constraints, known limitations, intent.
• # also switches a line off for investigation. Put it back or delete it; do not leave it.

Comments are the first thing in this course that is about being read by other people rather than by Python. The next chapter is about something Python reads very strictly indeed — the whitespace at the start of your lines.