When writing Python code, it is always a good practice to make your code clean and easily understandable. Organizing the code, giving variables and functions descriptive names are several ways to do this.
Another way to improve the readability of your code is to use comments. A comment is a human-readable explanation or annotation that is used to explain the code. For example, if you wrote a complex regex, you add a comment describing what the code does.
Adding comments to your Python code will save you a lot of time and effort when you look at your code in the future. Let’s say you want to change a script that you wrote a few months or years ago. The chances are that you will not remember why you wrote some complicated piece of code unless you added a comment. The comments also help other developers to understand your code and its purpose.
Comments should be short and to the point. Do not explain something that is obvious to the reader.
This article covers the basics of writing comments in Python.
Writing Comments in Python
Python ignores everything written on the line after the hash mark (#).
Comments can be added at the beginning on the line or inline with other code:
# This is a Python comment.
print("Hello World") # This is an inline Python comment.
The blank space after the hash mark is not mandatory, but it will improve the comment’s readability.
A hash character within a string literal doesn’t indicate the start of a comment line. It is simply a hash character:
paragraph = "# Hash inside quotes is not a comment."
Comments should be at the same indent level as the code beneath it:
```py
def factorial(n):
if n == 0:
return 1
else:
# Use the factorial function
return n * factorial(n-1)
If your text editor supports syntax highlighting, comments are usually represented in green.
Comments are also useful when debugging a script. Instead of deleting some lines or blocks, you can comment them out:
# for fruit in fruits:
# print(fruit)
Multiline Comments in Python (Comment Blocks)
Unlike other popular programming languages, Python supports only single line comments.
The simplest way to write multiline comments in Python is to add single line comments one after another:
# This is the first line.
# This is the second line.
Another option is to use docstrings.
Docstrings are multiline string literals that are used to document what a module, function, class, or method does.
A docstring starts and ends with triple double quotes (""") and can span on one or multiple lines:
"""This is
a multiline
docstring.
"""
Docstrings are not technically comments. When a docstring occurs as the first statement in a module, function, class, or method, it ends up in the bytecode and becomes the __doc__ special attribute of that object. You should prefer using regular single-line hash comments.
Shebang
If you’re reading Python scripts, you might notice that on some of them the first line start with the #! characters and the path to the Python interpreter:
#!/usr/bin/env python3
This sequence of characters is called shebang and is used to tell the operating system which interpreter to use to parse the rest of the file. Scripts that start with shebang and are executable can be run in the terminal without typing python before the script name.
Because the shebang line starts with the hash character, it is considered as a comment and automatically ignored by the Python interpreter.
Conclusion
Writing comments is a good practice and helps other developers, including future self, to understand what the code does. In Python, everything after the hash mark (#) and until the end of the line is considered to be a comment.
If you have any questions or feedback, feel free to leave a comment.