Python Comments

What are comments in Python?

Comments are notes written alongside source code for people who read and maintain the program. The Python interpreter ignores ordinary comments during execution, so they do not change the program’s result.

1. Single-line comments

Start a comment with the hash character, #. Everything after the hash on that line is treated as a comment:

# Display a welcome message
print("Welcome to Python")

Use comments to explain why code exists, a business rule, or a non-obvious decision. Avoid comments that simply repeat the code.

2. Inline comments

An inline comment appears after a statement. Keep it short and leave enough space so the code remains easy to scan:

timeout = 30  # seconds allowed for the request
print(timeout)

Too many inline comments can make a line difficult to read. If the explanation is long, place it above the statement or improve the name of the variable.

3. Multiline comments

Python does not have a separate multiline-comment syntax. The clearest approach is to use a hash on every line:

# This calculation uses the customer’s
# approved discount and keeps the final
# amount greater than or equal to zero.

Most editors can add or remove the hash from several selected lines at once.

Are triple quotes comments?

Triple-quoted text uses a multiline string literal, not a true comment. A standalone string that is not assigned may be discarded after it is evaluated, but it is still a string and can add unnecessary work or confuse documentation tools. Use # for comments.

"""This is a string literal, not a normal comment."""

print("Continue running")

4. Docstrings

A docstring is a string placed as the first statement in a module, class, function, or method. Python stores it as documentation and exposes it through __doc__ and tools such as help():

def add(first, second):
    """Return the sum of two numbers."""
    return first + second

print(add.__doc__)
help(add)

Docstrings should describe the public purpose, parameters, return value, raised exceptions, or important usage rules. They are part of the program’s documentation and can be used by IDEs and documentation generators.

Comments versus docstrings

Good commenting practices

• Write comments for intent and reasoning, not for obvious syntax.
• Keep comments accurate when the code changes.
• Use clear names so fewer explanatory comments are needed.
• Use docstrings for reusable functions, classes, modules, and public APIs.
• Remove temporary debugging comments before committing production code.
• Do not put passwords, tokens, personal data, or secret configuration in comments.

Example with comments and a docstring

def calculate_total(price, quantity):
    """Return the total price for a quantity of items."""
    # Validate the input before performing the calculation.
    if quantity < 0:
        raise ValueError("quantity cannot be negative")
    return price * quantity

print(calculate_total(25, 3))

The docstring explains the function’s public purpose, while the inline comment explains a decision inside the implementation.