Writing Comments in Python

You write code for two audiences. Python reads it to execute instructions. People read it to understand what you built and why. Comments are how you talk to the second audience.

After learning how indentation structures Python code, the next skill is adding notes that make your intent clear.

Single-line comments

A comment in Python starts with a hash character (#). Everything from the # to the end of the line is ignored by Python:

python

# This entire line is a comment.
print("Hello")  # This part after the hash is also a comment.

Comments can sit on their own line or at the end of a code line. Python treats them as if they do not exist. They have zero effect on how the program runs.

Use a single-line comment when you need to note something short. Keep it on its own line above the code it describes:

python

# Convert temperature from Celsius to Fahrenheit.
fahrenheit = celsius * 9 / 5 + 32

Inline comments

An inline comment sits on the same line as code. Use at least two spaces between the code and the #. This visual gap makes the comment easier to spot:

python

discount = 0.15  # Apply 15% member discount.

Inline comments are best for short clarifications. If the explanation takes more than a few words, move it to its own line above the code instead. Overusing inline comments makes code harder to scan.

Commenting multiple lines

Python does not have a built-in syntax for block comments like /* */ in C-style languages. The standard approach is to put # at the start of every line in the block:

python

# The following calculation accounts for regional tax rates.
# Each rate was verified against the official 2026 tax tables.
# Do not modify without checking the source data.
final_price = base_price + regional_tax(base_price, region)

Most editors can toggle comments on a selected block. In VS Code, select the lines and press Ctrl+/ (Windows/Linux) or Cmd+/ (macOS). In PyCharm, the same shortcut applies. This adds or removes # from every selected line at once.

Triple-quoted strings as block comments

You may see triple-quoted strings used as multi-line comments:

python

"""
This script processes sales data from the daily CSV export.
It was written in July 2026 to replace the old spreadsheet workflow.
"""

This works because Python creates a string object and then discards it since it is not assigned to a variable. However, this is not technically a comment. It is a string literal that happens to be ignored.

The important difference: triple-quoted strings inside a function or class definition, when placed as the first statement, become docstrings. Python stores them and makes them accessible at runtime. A # comment is always invisible to Python.

Use # for regular comments. Triple-quoted strings are fine for temporary block comments during development, but they are not the official way.

Docstrings

A docstring is a string literal that appears on the first line inside a module, function, class, or method. Python attaches it to the object's __doc__ attribute, and tools like help() display it:

python

def celsius_to_fahrenheit(celsius):
    """Convert a Celsius temperature to Fahrenheit.
 
    Accepts a numeric value and returns the equivalent
    temperature in degrees Fahrenheit.
    """
    return celsius * 9 / 5 + 32

Now help(celsius_to_fahrenheit) shows the docstring to anyone exploring the code.

Docstrings use triple double-quotes ("""). The convention is described in PEP 257, Python's docstring style guide. For now, know that they exist and that they are different from regular comments. You will use them more when you start writing your own functions.

What to write in a comment

A comment should answer the question "why was this done?" rather than "what does this code do?" The code already answers the what. For example, avoid restating the obvious:

python

# Bad: repeats what the code already says.
# Add x and y.
result = x + y
 
# Good: explains a non-obvious choice.
# Compensating for sensor calibration drift observed in July 2026.
result = x + y + 0.03

Good comments explain intent, warn about edge cases, or document decisions:

python

# The API returns USD by default. Explicit conversion is needed for CAD.
price_cad = price_usd * usd_to_cad_rate
 
# This loop uses a while instead of for because the list
# grows dynamically during iteration.
while unprocessed:
    item = unprocessed.pop()
    if item.has_dependencies():
        unprocessed.extend(item.resolve_dependencies())

What not to comment

Do not comment out dead code and leave it. Code that is commented out clutters the file and makes readers wonder whether it matters:

python

# old_total = sum(items)  # Remove this. Use version control instead.
total = sum(items) + tax

If you use Git, you can always recover deleted code from the history. Delete it cleanly.

Do not write misleading comments. A comment that says one thing while the code does another is worse than no comment. When you change code, update the comments that describe it.

Do not over-comment. Not every line needs an explanation. If you have named your variables well, the code often speaks for itself.

Comments during debugging

When you are trying to fix a bug, temporarily commenting out lines helps you isolate the problem:

python

print("Starting processing...")
# process_data(items)  # Temporarily disabled to isolate the error.
print("Processing complete.")

This is a valid use of commented-out code during active debugging. Just remember to remove or restore it before committing your work. If the bug persists, read the error output carefully. The article on reading Python error messages walks through common error patterns.

Comments and the Python community

Python has a strong culture around readable code. The language itself enforces indentation. PEP 8 extends this philosophy to naming, spacing, and commenting. Following the community conventions means other Python developers can read your code without friction.

Good comments are part of that culture. They are not extra credit. They are what turns a script you wrote last week into something you can still understand next month.

Now that you can structure code with indentation and annotate it with comments, the next step is producing output. Continue to printing output in Python.