How to Use a Python Comment: Block, Inline, and Multiline (2023)

Materials required: Latest version of Python (Python 3), an integrated development environment (IDE) of your choice (or terminal), and a stable internet connection.

Prerequisites/helpful expertise: Basic knowledge of Python and programming concepts

Using comments correctly makes your code easier to understand. They’re essential for collaborative projects, code documentation, testing, and debugging. By the end of this tutorial, you will be able to use Python comments strategically to write more readable code.

Glossary

To add a comment in Python, follow these four steps:

1. Make sure your comment begins at the same indent level as the code it's about.
2. Begin with the hashtag (#) and a space. The hash character tells the interpreter to ignore the rest of the line of code.
3. Write your comment.
4. Close your comment with a newline. Python will start reading your code again after the line containing the comment ends.

Example:

12345print(5 + 10)y = 20 * 5print(y)# Hi, this is a commentprint("This is a print statement")

As you can see from this code, the interpreter will run the first three lines, skip the comment, and run the last line. The output should look like this:

Inline commenting in Python

An inline comment exists on the same line as a statement. You can create an inline comment by adding the hash character to the end of the line you want to comment on. This format is ideal for comments that provide context for the code. Here’s what it looks like:

12def price_adjust(price): return price * 0.13 #Price increase to adjust for inflation rate

Guidelines for inline Python comments

It is recommended to use inline comments sparingly to keep your code readable. The bulleted list below contains a few tips for ensuring your comments are necessary and concise:

• Avoid using comments to explain what your code does. If your code is too complex for other programmers to understand, consider rewriting it for clarity rather than adding comments to explain it.
• Focus on the why and the how.
• Make sure you’re not reiterating something that your code already conveys on its own. Comments should never echo your code.

Examples of helpful vs. unhelpful comments

Unhelpful:

123statetax = 1.0625 # Assigns the float 1.0625 to the variable 'statetax'citytax = 1.01 # Assigns the float 1.01 to the variable 'citytax'specialtax = 1.01 # Assigns the float 1.01 to the variable 'specialtax'

The comments in this code simply tells us what the code does, which is easy enough to figure out without the inline comments. Remember, focus on the why and the how, rather than the what.

Helpful:

123statetax = 1.0625 # State sales tax rate is 6.25% through Jan. 1citytax = 1.01 # City sales tax rate is 1% through Jan. 1specialtax = 1.01 # Special sales tax rate is 1% through Jan. 1

In this case, it might not be immediately obvious what each variable represents, so the comments offer helfpul real-world context. The date in the comment also indicates when the code might need to be updated.

Python has no built-in methods for multiline commenting. However, you can still use the hash character to comment several single-line comments. Here’s an example:

12# You can create a multiline comment# by adding the hash symbol to each line

How to comment out a block of code in Python

In Python, a code block is defined as multiple lines of code grouped on the same indentation level. If you have a larger block of code to comment, you may consider using documentation strings (docstrings) rather than the block comment method above. Docstrings are the string literals appearing directly after the definition of a function. You can use them to associate documentation with classes, functions, modules, and methods, but you can also use them to comment out code.

One-line docstrings

To create a single-line docstring in Python, follow these three steps:

1. Make sure your docstring begins at the same indentation level as the scope.
2. Use a triple quote to start the string, followed by a phrase beginning with a capital letter and ending with a period.
3. Close the string with triple quotes.

There should be no blank lines before or after a single-line docstring. You should also always use double quote characters for triple-quoted strings to align with the docstring convention in the Style Guide for Python Code.

Example:

1''' This is a comment using string literals with triple quotes '''

Multiline docstrings

Another way to create a multiline comment is to wrap it inside a set of triple quotes, similar to a multiline docstring. Technically, this is not a comment; it’s a string that isn’t assigned to any variable. This means that the interpreter will read the code but will not do anything with it. Here’s what the syntax should look like when you use this method:

Example:

12345'''This is a multilinecomment using string literalswith triple quotes'''

What is the difference between comments and docstrings in Python?

Although the docstring method does give you multiline comment functionality, remember that they are not technically comments. They are strings that are not assigned to any variable, allowing the program to ignore them at runtime. You can further compare and contrast Python comments and docstrings with the following chart:

You can use Python comments to create reminders for yourself or leave helpful documentation for others. They provide users with a way to communicate logic, algorithms, and formulas in source code without affecting the program’s execution. In addition to documenting code, you can use Python comments for testing and debugging.

Using Python comments for testing

There are several ways to use Python comments for testing and debugging purposes:

• Commenting out new code to ensure smooth implementation
• Trying out various programming methods by commenting out code and running each one to compare results
• Pinpointing the source of an error by commenting out and running parts of a program systematically

Example:

123a = 2 + 5#b = 7 + "four"c = "eight" + "zero"

The second line (b = 7 + "four") will cause an error, but if we comment it out, our code will run properly. Commenting is a good way to test which line of your code may contain an error during debugging.

Key takeaways

• Comments and docstrings should be made at the same indentation level as the code they’re about.
• Comments begin with a # and a space.
• Docstrings begin and end with triple quotes.
• Python has no built-in function for multiline comments, but you can use several lines beginning with hash characters or docstrings.
• Comments should be about the why and the how.
• Docstrings should be about the what.

Resources

You can stay up to date on Python tips and releases by getting involved with the Python community. Subscribe to the free Python email newsletter or connect with peers by joining the Python programming Slack channel.

• Style Guide for Python Code
• Being a Python Developer: What They Can Do, Earn, and More
• Python syntax tutorial
• Python traceback tutorial

Continue building your Python expertise with Coursera.

Take the next step in mastering the Python language by completing a Guided Project like Testing and Debugging Python. For a deeper exploration of the language that rewards your work with a certificate, consider an online course like the Python 3 Programming Specialization from the University of Michigan.