Python Comments and Docstrings: How to Write Helpful Notes in Code

A comment is a note for humans. Python ignores it completely when running your program. Good comments explain why code exists, warn about surprises, and make programs easier to understand months later, for others and for yourself.

Single-line comments#

Everything after a # on a line is a comment:

# This program calculates a total
price = 250   # price of one item
qty = 3
print(price * qty)

750

• A comment on its own line describes the code below it.
• A comment after code on the same line is an inline comment. PEP 8 recommends at least two spaces before the #.

Multi-line comments#

Python has no special multi-line comment syntax. Use a # on each line:

# Calculate the delivery fee:
# - orders over 500 ship free
# - otherwise, a flat fee of 40 applies

Most editors comment or uncomment several selected lines at once with Ctrl + / (Cmd + / on macOS).

Docstrings#

A docstring is a string in triple quotes placed as the first line inside a function, class or file. It documents what the code does, and unlike a comment, Python keeps it so tools can display it:

def area(width, height):
    """Return the area of a rectangle."""
    return width * height

print(area(4, 5))
print(area.__doc__)

20
Return the area of a rectangle.

Editors show docstrings when you hover over a function, and help(area) prints them. Longer docstrings can span several lines:

def area(width, height):
    """Return the area of a rectangle.

    width and height must be positive numbers.
    """
    return width * height

Temporarily disabling code#

Putting # in front of a line "comments it out", which is useful while testing:

# print("this line is switched off")
print("this one runs")

this one runs

Remove commented-out code before sharing your work. Version control (like Git) remembers old code far better than comments do.

Writing good comments#

Explain why, not what. The code already says what it does:

# Bad: repeats the code
count = count + 1  # add one to count

# Good: explains the reason
count = count + 1  # the first row is a header, so start counting from 1

Good comments:

• explain a decision or business rule ("tax is 18% for this category");
• warn about something surprising ("API returns dates in UTC");
• mark known limitations (# TODO: handle empty files).

Often the best comment is a better name: seconds_per_day = 86400 needs no comment, while x = 86400 does.

Common mistakes#

Practice#

def to_rupees(dollars):
    return dollars * 83

def to_rupees(dollars):
    """Convert an amount in US dollars to Indian rupees."""
    # Fixed example rate; a real app would fetch today's rate
    return dollars * 83

print(to_rupees.__doc__)

Convert an amount in US dollars to Indian rupees.

Key takeaway#