Comments in Python

To keep your code clean and organized, easy to maintain and collaborative, it's essential to use comments with Python.

Comments are strings that are not interpreted by Python.

Python Comment Syntax

The # Symbol

This is the unique comment character in Python. Everything that follows this symbol on a line is ignored by the interpreter.

# This is a comment
x = 42  # This too

In this example "This is a comment" and "This too" are not interpreted by Python.

Single-line Comment

It's possible to add a comment on a single line in Python: this is the most common practice.

# Initialize the counter to zero
counter = 0

Multi-line Comment

It's also possible to simulate a multi-line comment: as it's just multiple single-line comments one below the other.

# Line 1
# Line 2
# Line 3

It's important not to fall into the trap of using a docstring temporarily to make multi-line comments. This is a bad practice: they are reserved for documentation. 😬

PYTHON

"""
This block can be used to
temporarily disable a piece of code.
"""

General Best Practices

A good comment should not repeat what the code already says, but clarify what it doesn't say.

To be sure to make a good comment, it's appropriate to follow a few simple rules:

• Clear: always use simple vocabulary without excess (we abandon abstract phrases);
• Concise: avoid paragraphs, get straight to the point;
• Useful: a comment must always have added value.

For example, this is a bad example:

i = 0  # Set i to 0

On the other hand, this one is much better:

i = 0  # Counter used to avoid infinite loop

This comment indicates the developer's intention, which is not obvious from the single line of code.

Comment the intention, not the implementation. The code explains the "how", the comment should answer the "why".

When to Comment Your Code?

Not all pieces of code require a comment. You should comment in the right place and for the right reason.

Generally, a comment is justified when:

• The code is complex or unusual;
• A business rule is applied;
• A technical exception is made voluntarily (which can explain on the fly a technical choice);
• Or for a temporary solution (the famous # TODO: replace x with y comments)

Avoid commenting on the obvious, but never hesitate to document a technical decision or unconventional behavior.

Comments vs Docstrings

Comments and docstrings serve two distinct functions:

Docstrings describe what an object does.

Comments explain why or how something is done inside an object.

Frequently Asked Questions About Comments

Do comments slow down code execution?

No. Comments are completely ignored by the Python interpreter.

Is a comment mandatory?

No. Python doesn't require it. But the readability of your code depends heavily on it, especially in teams or for long-term projects.

How to learn Python?

You can follow our Python course! 😋