Python Block Comments: Best Practices, Shortcuts, and Docstrings Explained

When writing Python code, you often need to comment out multiple lines at once or write detailed descriptions for functions and classes.

Unlike C or Java, Python does not have a dedicated syntax for block comments (like /* ... */).

This leads to common questions:

• "Do I really have to type # on every single line?"
• "Can I just use triple quotes """ as a comment?"

In this guide, we’ll explore the best practices for writing block comments in Python, how to use editor shortcuts for bulk commenting, and the crucial difference between comments and docstrings.

---

Does Python Have a Block Comment Syntax?

The short answer is no. Python’s language specification only defines the # (hash) character to ignore everything from that point until the end of the line.

However, in practice, developers achieve block-style comments using two methods:

1. Prepending # to each line (The Recommended Way)
2. Using Triple Quotes """ (The "Pseudo-comment" Way)

---

Method 1: Using "#" on Every Line (Recommended)

This is the standard approach recommended by PEP 8, Python’s official style guide. While it looks like you have to type a lot, modern editors make this instantaneous.

# ==================================
# This is a block comment.
# When writing long descriptions,
# start each line with a hash symbol.
# ==================================

print("Hello, Python!")

Why this is the Best Practice:

• Official Standard: It’s the universally accepted way among Python developers.
• Indentation Safe: It works anywhere in your code without triggering syntax errors.

Pro Tip: Editor Shortcuts for Bulk Commenting

Don't type hashes manually! You can toggle comments for multiple lines at once using keyboard shortcuts.

Editor	Shortcut (Windows / Mac)
VS Code	Ctrl + / (Mac: Cmd + /)
PyCharm	Ctrl + / (Mac: Cmd + /)
Jupyter / Colab	Ctrl + / (Mac: Cmd + /)

---

Method 2: Using Triple Quotes """ (The Pseudo-comment)

Triple quotes (triple-double or triple-single quotes) are technically used to create multi-line strings. However, if a string is not assigned to a variable, Python’s interpreter evaluates it and then moves on, effectively ignoring it.

print("Process Start")

"""
This part is not executed.
Since it's not assigned to a variable,
it acts like a comment.
"""

print("Process End")

⚠️ Warning: The Indentation Trap

Because triple quotes are technically "string data," they must follow Python’s strict indentation rules. If your triple quotes are not aligned with the surrounding code, you will get an IndentationError.

def my_function():
    print("Start")

"""
Error! This is not aligned with the 
function's indentation level.
"""

Verdict: Use this only for temporary "parking" of large blocks of code during debugging. Do not leave these in your final production code as "comments."

---

Block Comments vs. Docstrings

Python has a special feature called Docstrings (Documentation Strings). While they use triple quotes, their purpose is entirely different from comments.

def add(a, b):
    """
    Adds two numbers and returns the result.

    Args:
        a (int): The first number.
        b (int): The second number.

    Returns:
        int: The sum of a and b.
    """
    return a + b

Docstrings placed immediately after a function or class definition are recognized by Python as official documentation. You can access them via help(add) or by hovering over the function in editors like VS Code.

Type	Syntax	Purpose
Comment	#	Notes for developers (Why/How).
Docstring	"""	Documentation for users (What it does).

---

Conclusion

To write clean, "Pythonic" code:

1. Use hashes (#) for all internal comments.
2. Master the Ctrl + / shortcut to save time.
3. Reserve triple quotes (""") exclusively for Docstrings and temporary debugging.

---

Originally published at: [https://code-izumi.com/python/block-comment/]