Python Comments

A # that appears in code, outside any string, starts a comment. It can take a whole line or follow code on the same line:

# Block comment: describes the next few lines
service_days = 90
label = "Rack #7"   # the # inside the quotes is part of the text

On the last line, the first # is inside a string, so it is ordinary text; only the second one starts a comment. Python decides by looking at whether the # is inside quotes, not by where it appears on the line.

Multiline comments are simply consecutive # lines. Most editors toggle them for a selection with Ctrl+/ (Cmd+/ on macOS). The same shortcut is the quickest way to comment out code temporarily while you test an idea. Delete commented-out code once the experiment is over; version control such as Git remembers old versions far better than a pile of disabled lines.

PEP 8 recommends a space after the # and at least two spaces before an inline comment.

The most valuable comments explain why the code does something, especially when the reason isn't visible in the code itself: a business rule, a workaround, a unit of measurement or a decision that looks odd at first glance.

# Bad: repeats the code
service_days = 90   # set service_days to 90

# Good: records a reason the code can't express
service_days = 90   # manufacturer warranty requires a check every 90 days

The first comment adds nothing a reader can't see. The second tells a future maintainer that changing 90 has consequences.

If you need a comment to explain what a confusing line does, first try making the code clearer: choose a better variable name, split a long expression into named steps, or move it into a function with a descriptive name. Clear code with a few reason comments is easier to maintain than unclear code with many explanatory ones.

A docstring is a string literal placed as the first statement in a module, function, class or method. By convention it uses triple double quotes:

def days_until_service(days_ridden):
    """Return how many days remain before the next service.

    A negative result means the bike is overdue.
    """
    return 90 - days_ridden

help(days_until_service)

Unlike a # comment, a docstring is kept by Python and stored on the function as days_until_service.__doc__. help(), editors and documentation generators all display it. Start with a one-line summary in the imperative ("Return...", "Calculate..."), then add details after a blank line if needed. PEP 257 describes the conventions.

You may see triple-quoted strings used as "multiline comments" in the middle of code. That works only because an unused string does nothing, but it is not a comment: Python still creates the string, and if it's the first statement of a function it becomes the docstring. Use # for comments and docstrings for documentation.

Comments are not checked by Python, so nothing warns you when they become false. A comment saying "service every 90 days" beside code that now uses 60 is worse than no comment, because the reader has to work out which one is right.

Treat comments as part of the code: when you change behaviour, read the nearby comments and docstrings and update them in the same edit. Code reviewers should check them too. Some notes have a deliberately short life: # TODO: remove after the spring sale marks work still to be done, and many editors list every TODO in a project. Clean them up when the work is finished, so they remain a reliable to-do list rather than background noise.

Task: document a maintenance calculation with a reason comment and a short function docstring. Write a function that takes the number of days since a bike's last service and returns True if it is due. Rental bikes are due after 60 days and private bikes after 120.

RENTAL_INTERVAL = 60    # rentals are ridden daily, so they wear faster
PRIVATE_INTERVAL = 120

def service_due(days_since_service, is_rental):
    """Return True if a bike needs servicing today."""
    limit = RENTAL_INTERVAL if is_rental else PRIVATE_INTERVAL
    return days_since_service >= limit

print(service_due(75, is_rental=True))    # True
print(service_due(75, is_rental=False))   # False

The comment records the reason for the difference; the docstring tells a caller what the function returns. For the worked check, ask what # represents in "Rack #7": it is a character in the string, because comment syntax only applies outside quotes.

The Python tutorial introduces comments, PEP 8 gives the style rules and PEP 257 covers docstring conventions. Next, learn the print() function in depth, and see PEP 8 style for the broader formatting rules. Practise with the Python exercises and the Python quiz.