How to Comment in Python

When you return to a Python script after several months, the code may be difficult to follow even if it worked perfectly when you wrote it. Clear names and a simple structure help, but some decisions still need an explanation.

Comments let you add those explanations directly to the source code. For example, a short comment can describe why a complex regular expression is needed or why a function handles an unusual edge case.

This article explains how to write single-line and multiline comments in Python, how comments differ from docstrings, and what the shebang line does.

Writing Comments in Python #

In Python, a comment starts with a hash mark (#) that is outside a string literal and continues to the end of the line. Python ignores the comment when parsing the code.

Comments can be added at the beginning of a line or inline with other code:

# This is a Python comment.
print("Hello World")  # This is an inline Python comment.

According to PEP 8 , a comment should start with a hash mark followed by a single space. Inline comments should also have at least two spaces between the statement and the hash mark.

A hash character within a string literal does not indicate the start of a comment line. It is simply a hash character:

paragraph = "# Hash inside quotes is not a comment."

Comments should use the same indentation level as the code they describe:

def factorial(n):
    if n == 0:
        return 1
    else:
        # Reduce the problem until n reaches the base case
        return n * factorial(n - 1)

Comments should explain why the code works a certain way rather than repeat what the code already says. Keep them short, accurate, and at the same indentation level as the code they describe.

You can also comment out code temporarily while debugging a script:

# for fruit in fruits:
#     print(fruit)

For longer-term changes, remove unused code and rely on version control instead of leaving large commented-out blocks in the file.

Multiline Comments in Python #

Python has no dedicated block comment syntax. To write a comment that spans several lines, add a hash mark to each line:

# Validate the input before processing it.
# Empty values are handled by the caller.

Most code editors and IDEs can add or remove the hash marks for several selected lines at once. The common shortcut is Ctrl + / on Linux and Windows or Cmd + / on macOS, although the exact shortcut depends on the editor.

Comments vs. Docstrings #

Triple-quoted strings are sometimes used as multiline comments, but they are string literals rather than comments. When a string literal is the first statement in a module, function, class, or method, Python stores it in the object’s __doc__ attribute. In that position, it is called a docstring .

A docstring can fit on one line:

def square(number):
    """Return the square of a number."""
    return number * number

Longer docstrings use the same triple double quotes and can span several lines. Use docstrings to describe public modules, functions, classes, and methods. Use # comments to explain implementation details within the code.

Python Shebang Line #

When reading Python scripts, you might notice that some begin with the #! characters followed by the path to the Python interpreter:

#!/usr/bin/env python3

This sequence is called a shebang . On Unix-like systems, the operating system reads it to determine which interpreter should run the script. If the script is executable, you can run it directly without typing python before the filename.

Python itself treats the shebang as a comment because the line starts with a hash mark.

Conclusion #

Python comments start with # and continue to the end of the line. Use them to explain decisions that are not clear from the code, and use docstrings to document modules, functions, classes, and methods. For a quick refresher on other Python syntax, see the Python cheatsheet .

About the authors

Dejan Panovski

Dejan Panovski is the founder of Linuxize, an RHCSA-certified Linux system administrator and DevOps engineer based in Skopje, Macedonia. Author of 800+ Linux tutorials with 20+ years of experience turning complex Linux tasks into clear, reliable guides.

View author page