Python Comments: A Human's Guide to Writing Notes Your Future Self Will Love

Let's be honest. Writing comments isn't the glamorous part of coding. It doesn't give you that same adrenaline rush as finally solving a complex algorithm. It feels a bit like doing the dishes after a great meal—necessary, but not exactly fun.

But what if I told you that writing good comments is one of the most kind and professional things you can do? Especially for one very important person: Your Future Self.

We've all been there. You open a Python script you wrote six months ago, and it might as well have been written by a stranger. You stare at a block of code, squinting, and think, "What on earth was I trying to do here?"

That's where comments come in. They're not just for explaining what the code does; they're for explaining why you did it that way. Let's break it down, not like a robot, but like a human helping another human.

The Basics: How to Write a Comment in Python

Python makes it easy. For short, single-line notes, just use the hash symbol (#).

python

# This is a single-line comment
calculation = 10 * 5  # You can also comment next to code

For longer comments or docstrings (more on those later), you use triple quotes (""" or ''').

python

"""
This is a multi-line comment.
It's perfect for explaining a complex function
at the top of your code or for docstrings.
"""

Beyond the "What": The "Why" is King

Any decent programmer can figure out what a piece of code does by reading it. The real magic of a comment is explaining the why.

Instead of this (which is just noise):

python

# Loop through the list of users
for user in users:
    # Check if user is active
    if user.is_active:
        # Send email
        user.send_email()

Try this (which adds context):

python

# We're migrating data on Tuesday. Only email active users to avoid bounce-backs.
# The `is_active` flag was added in API v2, so this loop is safe.
for user in users:
    if user.is_active:
        user.send_email()

See the difference? The second example tells a story. It gives context that isn't visible in the code itself. It explains the business logic or the reason behind a specific implementation.

Meet the Docstring: Your Function's Best Friend

A docstring is a special multi-line comment nestled right under a function, class, or module definition. Its job is to describe what the thing does.

Pythonistas love docstrings because tools like Sphinx can automatically generate beautiful documentation from them. But even if you're not building docs, they're incredibly useful.

python

def calculate_compound_interest(principal, rate, time):
    """
    Calculates the future value of an investment with compound interest.

    This is a powerful function, but the math can be opaque. This comment
    clarifies the formula we're using and what each parameter represents.

    Args:
        principal (float): The initial amount of money invested.
        rate (float): The annual interest rate (as a decimal, e.g., 0.05 for 5%).
        time (int): The number of years the money is invested for.

    Returns:
        float: The future value of the investment after compound interest.
    """
    return principal * (1 + rate) ** time

Now, anyone (including you in six months) can call help(calculate_compound_interest) and immediately understand how to use this function without reading a single line of its internal logic. That's powerful.

A Little Empathy: Writing for Your Audience

Good comments show empathy. You're writing for:

1. Your Future Self: The most important reader. You will forget your own reasoning.

2. Other Developers: Your teammates will thank you for making their lives easier.

3. Your Users: Clear docstrings become clear documentation, which makes your software better.

The Golden Rule: Keep it Clean & Relevant

The biggest mistake is letting comments get out of date. A comment that describes code that no longer exists is worse than no comment at all because it actively misleads.

A good habit: When you update code, check the comments around it. Do they still hold true? If not, update them or delete them. Treat your comments like part of the code itself—because they are.