Comments and readable code

Code is read far more often than it is written, and most of the reading is done by the person who wrote it, months later, with no memory of what they were thinking. Comments and naming are the two tools that make that reading cheap.

# Prices are held in paisa so no calculation ever produces a fraction.
chai_paisa = 25000
print(chai_paisa / 100)

250.0

Everything after a # on that line is ignored by Python. There is no multi-line comment syntax — you put a # on each line.

Explain why, not what

The commonest mistake is a comment that repeats the code in English.

# add 1 to count
count = 5
count = count + 1
print(count)

6

That comment earns nothing. Anyone who can read count + 1 already knows it adds one, and now there are two things to keep in step — the day someone changes the code to + 2, the comment becomes a lie.

A comment is worth writing when it says something the code cannot:

# The canteen counts a re-order as one visit, so do not increment here.
visits = 5
print(visits)

5

That is information no amount of staring at the code would recover. The code says what happens. The comment says why. If you find yourself describing what, the fix is usually a better name rather than a comment.

Names do most of the work

# hard to follow
d = 86400
n = 3
print(d * n)

259200

seconds_per_day = 86400
days_booked = 3
print(seconds_per_day * days_booked)

259200

Identical output, and the second version needs no comment at all. The names carry the explanation.

Python's convention is snake_case — lower case words joined by underscores — for variables and functions. Constants that never change are written in UPPER_SNAKE_CASE by convention; Python does not enforce it, it is a signal to the reader.

MAX_SEATS = 52
booked_seats = 47
print(MAX_SEATS - booked_seats)

5

A few naming habits worth adopting straight away:

• Say what it holds, not what type it is. student_names beats list1.
• Booleans read as a question. is_open, has_paid, can_order.
• Short names for short lives. i in a three-line loop is fine; i as a module-level variable is not.
• Do not abbreviate to save typing. You type it once and read it fifty times.

Magic numbers

A bare number in the middle of a calculation is a small mystery.

total = 1000
print(total * 1.17)

1170.0

What is 1.17? Six months later nobody knows whether it is tax, a service charge or a currency conversion, and nobody dares change it. Give it a name:

SALES_TAX = 1.17

total = 1000
print(total * SALES_TAX)

1170.0

Now it is searchable, changeable in one place, and self-explaining.

Whitespace, and the four-space rule

Python uses indentation to decide what belongs to what, so spacing is not cosmetic — it is syntax. The convention, and the one every editor defaults to, is four spaces per level.

marks = 72

if marks >= 50:
    print("Pass")
    if marks >= 80:
        print("Distinction")
else:
    print("Fail")

Pass

Two rules that avoid most indentation errors:

• Never mix tabs and spaces. They can look identical and Python treats them as different, producing a TabError that is invisible on screen. Set your editor to insert spaces when Tab is pressed and the problem disappears.
• Be consistent within a file. Four spaces everywhere.

Blank lines matter for reading too. One blank line separates steps inside a block; two separate top-level functions. That is the PEP 8 convention, and following it makes your code look like everyone else's, which is the point.

PEP 8, briefly

PEP 8 is the Python style guide. It is not enforced by the language and it is followed almost universally. The parts you will use daily:

# spaces around operators, and after commas
total = 250 + 120
items = ["chai", "paratha", "samosa"]

# no space just inside brackets
print(items[0])

# one statement per line
print(total)

chai
370

Also: keep lines under about 79 characters, put imports at the top of the file, and use blank lines rather than comment banners to separate sections.

Tools do this for you. black reformats a file to a consistent style and ruff reports the violations, so nobody has to argue about it in review.

Commenting out code

# is also how you disable a line without deleting it, which is useful while you are working:

print("first")
# print("second")
print("third")

first
third

Do not commit it. Commented-out code accumulates, nobody dares delete it because nobody knows if it is still needed, and version control already remembers every line you ever removed. If it is not running, delete it.

What good looks like

# Late fee is charged per started week, not per day, per the 2024 policy.
FEE_PER_WEEK = 50

days_late = 9
weeks_late = -(-days_late // 7)   # ceiling division

print(f"{weeks_late} week(s), fee {weeks_late * FEE_PER_WEEK}")

2 week(s), fee 100

Three comments' worth of value in two comments: one explains a business rule you could not deduce, the other flags a piece of arithmetic that is genuinely non-obvious. The names do the rest, and the f-string makes the output readable.

Next: getting input.