Comments and Readability
Writing code humans can actually read
In this lesson
A comment is a note in your code that Python ignores when it runs — written after a # — used to explain why something is done. Because code is read far more often than it’s written (usually by you, weeks later), you’ll learn to use comments well and to write clear code that needs fewer of them.
Explain it like I’m 5
A comment is a sticky note for humans. Python ignores it completely; it’s only there to help a person understand what the code is doing and, more importantly, why.
How comments work
Anything after a # on a line is a comment and is ignored by Python. Use them to explain reasoning that isn’t obvious from the code itself — a tricky calculation, a business rule, a ‘why we do it this odd way’.
Good comments explain why, not what
A comment that restates the code (# add 1 to count above count += 1) is noise. A comment that explains why (# skip the header row) earns its place. If you feel you need a comment to explain what a line does, that’s often a hint to rename a variable or split the line.
# Bad: comment restates the obvious
x = x + 1 # increase x by 1
# Better: a clear name removes the need for a comment
attempts_left = attempts_left - 1
# Good: comment explains a non-obvious reason
price = price * 1.2 # add 20% VAT
print(price)
Names and whitespace do most of the work
The best ‘documentation’ is clear names: seconds_remaining needs no comment. Blank lines group related steps; spaces around operators (x = a + b, not x=a+b) make lines easier to scan. Python’s style guide, PEP 8, codifies these conventions — you don’t need to memorise it, just absorb the habits.
# Cramped and cryptic
d=p*q+t
# Clear names and spacing — reads almost like English
price = 10
quantity = 3
tax = 2
total_due = price * quantity + tax
print(total_due)
32
Docstrings: documentation built into your code
There’s a special kind of comment called a docstring: a triple-quoted string placed as the very first line inside a function (or at the top of a file), describing what it does.
Unlike a # comment, a docstring is attached to the thing it documents — Python’s built-in help() reads it back to you, and editors show it as a tooltip. Get into the habit of writing one for anything whose purpose isn’t obvious from its name.
def area(width, height):
"""Return the area of a rectangle."""
return width * height
print(area(3, 4))
print(area.__doc__)
12 Return the area of a rectangle.
What character begins a comment in Python?
Python comments start with #; the rest of the line is ignored.
Which is the most useful comment?
Good comments explain why; the others merely restate the code.
Mini exercise (easy)
Rewrite this to need no comment: d = 86400 # seconds in a day. Use a descriptive variable name instead.
Do it here. Finish the code below and press Run to try your answer right in the browser — no setup needed.
# Rename d to seconds_per_day (no comment needed):
d = 86400
print(d)Name the variable after what it holds.
seconds_per_day = 86400
print(seconds_per_day)