Comments

Sometimes you need to explain what particular parts of your code are for. Luckily, Python allows you to fulfill your needs. You can leave special notes called comments. They are especially useful for beginners. Throughout this course, we will often use comments to explain our examples.

What is a comment?

Python comments start with a hash, #. Everything after the hash up to the end of the line is regarded as a comment and will be ignored when running the code.

print("This will run.")  # This won't run

In the example above, you can see what PEP 8 calls an inline comment. It's a comment written on the same line as the code.

A comment can also refer to the block of code that follows it:

# Outputs three numbers
print("1")
print("2")
print("3")

We intend to use comments primarily for learning purposes. Now, it's time to find out how to comment code properly.

Formatting comments

Although it is easy to write a comment, let's discuss how to do so according to the best practices.

To begin with, there should be one space after a hash mark. For inline comments, there should be two spaces between the end of the code and the hash sign. Putting more than two spaces between the end of the code and the hash mark is acceptable, but most commonly, there are exactly two spaces.

print("Learning Python is fun!")  # This is proper comment formatting
print("PEP-8 is important!")#This is a very bad example

Indent your comment to the same level as the statement it explains. E.g., the following example is wrong:

    # this comment is in the wrong place
print("This is a statement to print.")

A comment is not a Python command: it should not be too long. Following PEP-8, the comment length should be limited to 72 characters. It's better to split a long comment into several lines. You can do so by adding a hash mark at the beginning of each new line:

# Imagine this is an example of a very long comment that
# we need to spread over three lines, so we continue to
# write it even here.
print("The long comment above explains this line of code.")

Comments that span multiple lines are called multi-line or block comments. In Python, there is no special way to indicate them.

We hope our comments will help you understand our code examples better!

Summary

In this topic, we learned what comments are and what they're used for. The main points are:

• Comments are used to explain what particular parts of your code are for.

• Comments start with a hash, #.

• Comments are ignored during the execution of the code.

• Comments might be above a piece of code, inline, or form a block.

There are specific comment formatting rules you should follow according to PEP 8:

• There should be one space after a hash mark.

• For inline comments, there should be two spaces between the end of the code and the hash mark.

• The comment length should be limited to 72 characters. You can split a long comment into several lines forming a block.

• Indent your comment to the same level as the statement it explains.