How to Write Multiline Comments in Python

Introduction

Python does not have any built-in mechanism for writing multiline comments.

Definition of multiline comments

Prepend the `#` character to each line to comment multiline in Python. The ‘#’ is called an octothorpe.

In short, start every line with the # symbol consecutively, and you will get multiline comments.

# Use * for multiplication of a number

# The * is a multiplication operator in Python

# To print the value, use the print() function

print(3 * 7)

Output

21

To add a multiline comment, insert a # on each line before writing a code or sentence.

Why doesn’t Python have multiline comments?

Python doesn’t have a built-in mechanism for multiline comments because it is easily breakable. It also makes it impossible to comment out code with multiline strings, which may lead to indentation errors if you’re not careful.

Many developers identified that big blocks of commented-out code in production are bad. And creator of Python – Guido Van Rossum, is not a fan of multiline comments, so he did not propose it.

Using Multiline Strings as Comments

Another way to create multiline comments in Python is to use multiline strings or docstrings. Although it has a similar effect, this is used for documentation strings, not block comments.

If you are commenting on things temporarily, it is acceptable as a temporary measure.

Python provides two kinds of docstrings: one-line docstrings and multiline docstrings.

We will use multiline docstrings to create a block comment.

"""
Use * for multiplication of a number

The * is a multiplication operator in Python

To print the value, use the print() function
"""
print(3 * 7)

Output

21

One-line docstrings in Python

A one-line docstring fits into one line. A one-line docstring in Python begins with triple quotes (“””) and also ends with triple quotes (“””).

""" Use * for multiplication of a number """

print(3 * 7)

Output

21

As you can see, we have used triple-quoted strings to create something that resembles a multiline comment in Python.

You need to ensure you indent the first ” < UNK> < UNK> correctly; otherwise, you will get a SyntaxError.

It’s always considered a great practice to keep your comment clear, concise, and explanatory.

The ultimate goal of comment is to save time and energy for you and other developers collaborating with the project.

Use of Multiline Comments in Python

Documenting code

Documenting code means adding written explanations and descriptions to the code to help other developers understand how it works. It includes information about the purpose of the code, how it is intended to be used, and how it fits into the larger system.

Documenting code can also provide context for future maintenance and development efforts.

Improving the readability of code

Improving the readability of code means making the code easier to understand, follow, and modify.

Code improvement includes clear, concise, and descriptive names for variables, functions, and classes, organizing the code into logical blocks, and using appropriate comments and documentation.

Best Practices for Multiline Comments in Python

Placing comments at the beginning or end of a block of code

Placing comments at the beginning of a code block involves adding a comment before a section that explains what the code is doing.

Placing comments at the end of a code block involves adding a comment after a section that explains what the code has just done.

Using meaningful and descriptive text

You need to use meaningful and descriptive text to write comments and documentation that are clear, concise, and provide relevant information about the code. It helps other developers understand what the code is doing and why, making it easier to modify, maintain, and reuse.

  1. Be clear and concise: Avoid using technical jargon or overly complex language. Instead, write comments that are easy to understand for someone unfamiliar with the code.

  2. Focus on the purpose: Explain what the code does, not how it does it. Highlight the goals and objectives of the code, and describe its intended use.
  3. Provide context: Explain the reasoning behind a particular implementation choice or the context in which the code will be used. This can help others understand why the code was written the way it was.

Avoiding comments that are too lengthy or repetitive

You don’t have to write overly long comments or provide information that can be inferred from the code itself. This helps to keep the comments concise, focused, and relevant.

Lengthy comments can make the code harder to read and understand and can distract from the code itself. They can also make it challenging to locate the information relevant to the code.

FAQs

Are there any differences between single quotes and double quotes for multiline comments?

No, there is no difference between using single quotes or double quotes for multiline comments in Python.

Can I nest a multiline comment inside another multiline comment?

Each comment must be on its line(s) and cannot be nested within another comment.

Are there any specific guidelines for using multiline comments in Python?

It is best practice to use comments sparingly and only when necessary to explain complex code.

Can I include special characters or symbols in a multiline comment?

Yes, you can have special characters or symbols in a multiline comment.

Are there any conventions for writing comments for functions or classes in Python?

Keeping your lines of code to 79 characters or less is recommended by PEP 8, and inline comments and docstrings should not exceed 72 characters. If your comment is longer than that, please break it into multiple lines.

Most of the time, Comments should be brief and to the point.

Conclusion

There is no built-in mechanism to write multiline comments in Python, but you can prevent the # symbol to each line to comment multiline.

Further reading

How to comment block in Python

How to Create a Comment Block on Jupyter Notebook

How to Create a Comment Block on VSCode in Python

Leave a Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.