Comments

How and why to write comments — the art of making code readable for yourself and everyone else who will ever touch it.

"Code is written once but read many times — by your teammates, your future self, and sometimes you at 2am wondering what on earth you were thinking."

— ShurAI

What is a Comment?

A comment is a note you write in your code that Python completely ignores. It exists purely for humans — to explain what the code does, why a decision was made, or to leave a reminder. Comments start with the # symbol. Everything after # on that line is ignored by Python.

python

# This is a comment — Python ignores this line entirely
print("Hello")   # This is an inline comment — after the code

# Comments can be on their own line
# or after a line of code
x = 10    # store the value 10

Why Comments Matter

Beginners often ask: "If the code works, why add comments?" The answer is readability. Code that made perfect sense when you wrote it can become a mystery two weeks later. Comments solve this:

❌ Hard to understand

r = 0.18
t = 3
p = 50000
a = p * (1 + r) ** t
print(a)

✅ Instantly clear

# Compound interest calculator
rate       = 0.18    # 18% annual rate
years      = 3       # investment period
principal  = 50000  # initial amount (Rs.)
final      = principal * (1 + rate) ** years
print(final)

Same code. Same result. One is readable, one is a puzzle. In a real codebase, the left version costs time and causes mistakes. The right version saves both.

Single-Line Comments with #

The # character starts a comment that runs to the end of the line:

python

# ── Section Header ──────────────────────────────────
# Describe what a whole block of code is doing

tax_rate = 0.18         # GST rate for India
price    = 1000         # base price before tax
tax      = price * tax_rate
total    = price + tax   # final price with tax

print(total)              # 1180.0

Multi-Line Comments — Block Comments

Python has no dedicated multi-line comment syntax. For multiple lines, just use multiple # symbols, one per line:

python

# This function calculates the final price
# after applying the discount and tax.
# Formula: (price - discount) * (1 + tax_rate)
price     = 5000
discount  = 500
tax_rate  = 0.18
final     = (price - discount) * (1 + tax_rate)

Docstrings — Documentation Strings

Triple-quoted strings at the top of functions or files are called docstrings. They are a special kind of documentation that Python can read and display:

python

def calculate_bmi(weight, height):
    """
    Calculate Body Mass Index (BMI).

    Args:
        weight: body weight in kilograms
        height: height in metres

    Returns:
        BMI as a float (weight / height²)
    """
    return weight / (height ** 2)

# Python tools can read docstrings with help()
print(calculate_bmi.__doc__)

Commenting Out Code — For Debugging

You can temporarily disable a line by commenting it out. This is useful when testing or debugging — you keep the line without deleting it:

python

price    = 1000
discount = 200

# Testing without discount — commented out temporarily
# final = price - discount
final    = price

print(f"Final price: Rs.{final}")
# When testing done, uncomment the discount line

What Makes a Good Comment?

❌ Bad Comments

# Add 1 to x
x = x + 1

# Set y to 5
y = 5

Repeats what the code already says. Adds no value. Waste of space.

✅ Good Comments

# Increment attempt counter
attempts = attempts + 1

# Max retries before lockout
max_tries = 5

Explains purpose and context. Adds meaning the code alone does not express.

The Golden Rule of Comments

Comment the why, not the what. The code already shows what is happening. Comments should explain why you made a choice, what a formula means, or what a non-obvious value represents. If the code is clear on its own, a comment may not be needed at all.

Real Example — Well-Commented Program

python

# ── Electricity Bill Calculator ─────────────────────
# Rates based on Maharashtra electricity tariff 2024

units_used    = int(input("Units consumed this month: "))

# Tiered pricing: first 100 units are cheapest
if units_used <= 100:
    rate = 3.50    # Rs. per unit for slab 1
elif units_used <= 300:
    rate = 5.00    # Rs. per unit for slab 2
else:
    rate = 6.50    # Rs. per unit for slab 3 (heavy usage)

base_charge  = units_used * rate
fixed_charge = 100                     # monthly fixed fee, non-negotiable
total        = base_charge + fixed_charge

print(f"Units     : {units_used}")
print(f"Rate      : Rs.{rate}/unit")
print(f"Total     : Rs.{total:.2f}")

"The best comment is a well-named variable. The second best is a clear sentence explaining why — not what."

— ShurAI

🧠 Quiz — Question 1

What happens when Python encounters a # character in code?

🧠 Quiz — Question 2

What are triple-quoted strings at the top of a function called?

🧠 Quiz — Question 3

What is the golden rule of writing good comments?

🧠 Quiz — Question 4

What is one practical use of commenting out code?