Python Comments – Single Line, Multi-line, and Docstrings

Single-Line Comments

Any text after a # symbol on a line is a comment. Python ignores everything from the # to the end of that line.

# This is a full-line comment
print("Hello")  # This is an inline comment

# Multiple single-line comments:
# Step 1: Get user input
# Step 2: Validate it  
# Step 3: Process it

Multi-Line Comments (Triple Quotes)

Python doesn't have a dedicated multi-line comment syntax. The convention is to use triple-quoted strings (they are technically string literals that get assigned to nothing, so Python ignores them).

"""
This is a multi-line
"comment" using triple quotes.
Python evaluates it as a string but discards it.
"""

print("Code continues here")

Docstrings – Documentation Strings

Docstrings are triple-quoted strings placed as the first statement in functions, classes, or modules. Unlike regular comments, docstrings are accessible at runtime via .__doc__ and are used by documentation generators.

def calculate_area(radius):
    """
    Calculate the area of a circle.

    Args:
        radius (float): The radius of the circle.

    Returns:
        float: The area of the circle.
    """
    import math
    return math.pi * radius ** 2

print(calculate_area(5))
print(calculate_area.__doc__)

When to Write Comments – Best Practices

Comments should explain WHY, not WHAT. Well-named code explains itself. Only add comments when the reasoning is not obvious.

# ❌ Useless comment - the code already says this
x = x + 1  # increment x by 1

# ✅ Useful comment - explains non-obvious behavior
x = x + 1  # Offset by 1 to convert 0-based index to 1-based display

# ✅ Useful: explains a workaround
# Using int() instead of round() here because the legacy API
# expects truncated values, not rounded (see ticket #1234)
result = int(value)

Comments: Explain Why, Not What

Python ignores everything after # on a line. But good comments don't repeat the code — they explain the reasoning the code can't show. A comment restating the obvious is noise; one capturing a decision is gold.

x = x + 1          # ❌ "add one to x" — the code already says this
retries = 3        # ✅ vendor API rate-limits after 3 rapid calls

# TODO: replace with pagination once the endpoint supports it
data = fetch_all()

Key distinction: a # comment is stripped and invisible at runtime; a docstring (a string literal as the first statement in a function, class, or module) is stored on the object and shown by help() and IDE tooltips. Document public functions with docstrings, use # for in-line reasoning, and delete commented-out code — that's what version control is for.

Interview Questions on Comments

• How do you write a single-line comment in Python?
• Does Python have true multi-line comment syntax?
• What is a docstring and how is it different from a regular comment?
• How do you access a function’s docstring at runtime?
• What is the difference between # comments and triple-quoted strings?
• What does PEP 257 cover?
• When should you avoid writing a comment?

Related Topics