Comments — notes to your future self

The # character

Anything after a # on a line is ignored by Python. Use this for notes.

# Read the raw export the finance team dumps in this folder every Monday
raw = pd.read_csv("monday_dump.csv")

# Drop the rows where the customer column is blank — they're rejected orders
clean = raw.dropna(subset=["customer"])

Block comments

Multiple lines, each starting with #. There's no /* ... */ in Python.

# --- Configuration ---
# Change these once a month after the price review meeting
TAX_RATE = 0.08
SHIPPING_FLAT = 7.50

Docstrings — comments for functions

A docstring is a triple-quoted string right under a function's def line. Tools and IDEs use it to show the function's help.

def cents_to_dollars(cents):
    """Convert an integer cents value to a float dollars value.

    Example:
        cents_to_dollars(1299) -> 12.99
    """
    return cents / 100

When comments help — and when they're noise

Good comments explain why, not what:

# Bad — restates what the code already says
x = x + 1  # add 1 to x

# Good — explains the why
x = x + 1  # account for the off-by-one in the upstream CSV