Master Python Comments: Best Practices and Common Pitfalls

Today we will learn some simple and easy content. If you are just starting with Python, one of the first things you need to master is how to add comments to your code. Adding a # symbol is easy, but what about multi‑line comments? Are triple quotes used? Any shortcuts? Let’s explore the proper way to add comments in Python and the mistakes to avoid.

What exactly are comments in Python?

In Python, comments are lines that the interpreter ignores. Their purpose is to explain, guide, and clarify your logic so that other developers (or your future self) can understand the code.

Python has two types of comments:

Single‑line comments

Multi‑line or block comments

Although Python natively supports using # for single‑line comments, unlike C, C++ or JavaScript it does not have a built‑in syntax for multi‑line comments. So what should we do?

Python style: using # to write multi‑line comments

<code># This is the first line
# This is the second line of a multi‑line comment
# Used to explain some important content</code>

Why this is best practice:

Completely ignored by the interpreter

IDE recognises it as a real comment

Works in all Python versions

Keeps code readable

Note: Most editors (e.g., VS Code or PyCharm) let you select a block of code and press Ctrl + / (Windows/Linux) or Cmd + / (Mac) to comment multiple lines at once.

Common mistake: using triple quotes ( ''' ''' or """ """ )

Let’s correct a common misconception:

<code>''' 
This looks like a comment, 
but it is actually a string! 
Python ignores it only because it is not assigned, 
but it is not a real comment. 
'''</code>

Although Python does not raise an error, this is not a true comment; it is an unassigned string literal.

Why you should not use it:

May unnecessarily consume memory

Can mislead readers into thinking it is a comment

In some contexts it may be interpreted as a docstring

May be flagged by code‑review tools or linters

Special case: docstrings

Docstrings are a legitimate use of triple quotes, but only when placed immediately after a function, class, or module definition.

<code>def add(a, b):
    """This function returns the sum of two numbers."""
    return a + b</code>

This is the only valid situation for using triple quotes.

They are used to generate documentation, e.g., with pydoc and similar tools.

Note: Do not confuse docstrings with multi‑line comments!

IDE shortcuts to comment like a pro

Want to save time? Most modern IDEs and editors provide quick shortcuts to comment multiple lines at once.

Common shortcuts:

VS Code:

Windows/Linux: Ctrl + /

Mac: Cmd + /

PyCharm:

Windows/Linux: Ctrl + /

Mac: Cmd + /

Jupyter Notebook:

Windows/Linux: Ctrl + /

Mac: Cmd + /

Key points and taboos for commenting

To help developers and search engines, here is a checklist of do’s and don’ts for Python comments.

Do’s:

Use # to write real multi‑line or block comments

Keep comments concise and useful

Use IDE shortcuts to toggle comment blocks

Only use docstrings in functions, classes, and modules

Don’ts:

Do not use triple quotes for ordinary comments

Do not write overly long or irrelevant comments

Do not leave commented‑out dead code in production

Do not confuse documentation strings with regular comments

Real case: commenting a logic block

Below is how to correctly comment a function in Python:

<code>def process_user_data(data):
    # Step 1: Clean input data
    clean_data = clean_input(data)
    # Step 2: Validate cleaned data
    if not validate(clean_data):
        return "Invalid data"
    # Step 3: Process and return result
    return analyze(clean_data)</code>