Python Comments Explained — Single-Line, Multi-Line and Best Practices

Every line of code you write today is a mystery you'll need to solve tomorrow. That sounds dramatic, but ask any developer who's opened a file they wrote six months ago — without comments, even your own code can look like a foreign language. Comments are the single cheapest investment you can make to keep your code readable, maintainable, and friendly to every person who touches it after you.

Python runs fast. It processes your instructions line by line, but it skips comments entirely — they exist purely for people, not machines. This solves a real problem: code tells the computer WHAT to do, but it rarely explains WHY a decision was made, what a tricky block is trying to achieve, or what a number like 0.0875 actually represents (is that a tax rate? a discount? who knows). Comments fill that gap.

By the end of this article you'll know exactly how to write single-line comments, how to fake multi-line comments the Pythonic way, how to use docstrings to document functions properly, and — most importantly — when to write a comment versus when to just write cleaner code. You'll also see the mistakes that trip up beginners and the answers that impress interviewers.

Single-Line Comments — The Workhorse You'll Use Every Day

A single-line comment in Python starts with the hash symbol #. Everything after that # on the same line is ignored by Python. That's the whole rule. There's nothing to install, no special mode to activate — just type # and write your note.

You can put a comment on its own line above the code it describes, which is called a 'block comment'. Or you can put it at the end of a line of code, which is called an 'inline comment'. Both are valid, but block comments are usually easier to read because they don't crowd the code.

Here's the key habit to build early: comment the WHY, not the WHAT. If you write total_price = price + tax and then comment # adds price and tax, that comment adds zero value — anyone can see that. But if you comment # tax is added here because EU law requires it to appear in the final total, now you've explained something the code can't explain itself. That's what comments are for.

# This program calculates the final price a customer pays, including sales tax.
# Written by: TheCodeForge Team

item_price = 49.99          # Price of the item in US dollars
tax_rate = 0.0875           # 8.75% sales tax — required by local tax law

# Multiply the item price by the tax rate to get the tax amount
tax_amount = item_price * tax_rate

# Add the original price and the tax to get the total the customer owes
total_price = item_price + tax_amount

# Round to 2 decimal places so we get a clean dollar amount (e.g. 54.37, not 54.374375)
final_price = round(total_price, 2)

print("Item price:  $", item_price)
print("Tax amount:  $", round(tax_amount, 2))
print("Total price: $", final_price)

Multi-Line Comments — What Python Actually Does (and Doesn't Have)

Here's something that surprises beginners: Python has no official multi-line comment syntax. Languages like Java and JavaScript have / ... / block comments, but Python never added an equivalent. So how do Python developers write longer notes that span multiple lines?

The answer is simple — you just start each line with its own #. Stack as many lines as you need, each prefixed with a #. Python treats each one as a separate single-line comment, but visually they read as a block. This is the officially recommended approach in Python's own style guide (PEP 8).

You'll also see beginners use triple-quoted strings (''' or """) as a workaround for multi-line comments. A string that isn't assigned to a variable and isn't attached to a function is technically just a value Python evaluates and immediately throws away — so it behaves like a comment in practice. However, this is not a true comment, and there's one important exception: when a triple-quoted string appears as the very first statement inside a function, class, or module, it becomes a docstring — a documented description that tools and IDEs can actually read. More on that in the next section.

# ─────────────────────────────────────────────
# APPROACH 1 — The Pythonic Way (Recommended)
# Stack multiple single-line comments.
# This is what PEP 8 (Python's style guide) recommends.
# ─────────────────────────────────────────────

# This function converts a temperature from Celsius to Fahrenheit.
# Formula: F = (C × 9/5) + 32
# This conversion is needed because our US-based clients expect
# temperatures displayed in Fahrenheit, while our database stores
# all values in Celsius for international consistency.
def celsius_to_fahrenheit(celsius_temp):
    fahrenheit_temp = (celsius_temp * 9 / 5) + 32
    return fahrenheit_temp


# ─────────────────────────────────────────────
# APPROACH 2 — Triple-quoted string used as a comment
# This works but is not technically a comment.
# Only use this for docstrings (see next section).
# ─────────────────────────────────────────────

"""
This block is a string that gets evaluated and discarded.
Python doesn't execute it as code, and it has no variable to store it,
so it effectively acts like a comment — but this is a workaround,
not an official language feature.
"""

boiling_point_celsius = 100
boiling_point_fahrenheit = celsius_to_fahrenheit(boiling_point_celsius)

print("Boiling point in Celsius:   ", boiling_point_celsius, "°C")
print("Boiling point in Fahrenheit:", boiling_point_fahrenheit, "°F")

Docstrings — Comments That Your Code Can Actually Read

A docstring is a special triple-quoted string placed as the very first statement in a function, class, or module. It's Python's official way of documenting what a piece of code does — and unlike a regular comment, Python stores the docstring and makes it accessible at runtime via the __doc__ attribute and the built-in help() function.

Think of a regular comment as a sticky note on your desk — helpful to you, invisible to everyone else. A docstring is like a label on a product — it's built into the thing itself and anyone can read it just by inspecting the object.

Docstrings follow a convention: the first line is a short, one-sentence summary of what the function does. If you need more detail, add a blank line, then a longer description, then document the parameters and return value. You don't have to memorise a rigid format right now — just know that the first line matters most and should be a clear, complete sentence.

For beginners, the most important takeaway is this: every function you write should have a docstring. It takes ten seconds, and it pays back tenfold.

def calculate_discount_price(original_price, discount_percent):
    """
    Calculate the price of an item after applying a percentage discount.

    This function takes the original price and a discount percentage,
    computes the amount saved, and returns the final discounted price
    rounded to two decimal places.

    Parameters:
        original_price  (float): The full price of the item before discount.
        discount_percent (float): The discount as a percentage (e.g. 20 for 20%).

    Returns:
        float: The price the customer actually pays after the discount.

    Example:
        calculate_discount_price(80.00, 25) returns 60.0
    """
    # Convert the percentage to a decimal (e.g. 20% becomes 0.20)
    discount_as_decimal = discount_percent / 100

    # Calculate how much money is being taken off
    amount_saved = original_price * discount_as_decimal

    # Subtract the saving from the original price to get what the customer pays
    discounted_price = original_price - amount_saved

    return round(discounted_price, 2)


# ── Demonstrating that the docstring is stored and readable at runtime ──
print("--- Running the function ---")
original = 120.00
discount = 30  # 30% off

final_cost = calculate_discount_price(original, discount)
print(f"Original price:   ${original}")
print(f"Discount applied: {discount}%")
print(f"You pay:          ${final_cost}")

print("\n--- Reading the docstring at runtime ---")
print(calculate_discount_price.__doc__)

Frequently Asked Questions