Using comments in Python 3
Learn to write Pythonic code using comments and docstrings.

Why do you need comments?
Comments describe the functionality and intent of your Python code.
But as an author, don't you already know it? Consider these scenarios.
- A new colleague joins your team and is getting acquainted with the codebase. In the absence of relevant comments and documentation, he/she will have a hard time understanding its true purpose.
- You wrote a great application, a few years ago and it was working, until yesterday! Yesterday, one of the features broke. So you have decided to upgrade your application, but you don't know where to make the change to fix the feature, as there are no comments and you have forgotten what each function or class does over the years.
Comments and proper documentation come to your rescue in such scenarios. Here are some advantages of using comments in Python.
- Describe the intent and functionality of your code.
- Help fellow developers understand your work and provide better code reviews.
- Easier to remember the logic or algorithm behind a function or class
In Python, you can write comments in 3 different ways.
You will also learn about Good comments vs Bad comments in Python.
Single line Comments
You can use the hash symbol #
to write single-line comments in Python. Everything that comes after the hash symbol #
is ignored by the Python interpreter.
Code
# printing Hello World
print("Hello World!")
x = 10
y = 20
# Tuple Swap
x, y = y, x
str1 = "Pylenin loves Python"
# Return the first and last character
print(str1[0] + str1[-1])
If single-line comments are placed on the same line as a Python statement, they are called Inline comments. Below is an example.
Code
salary = 100000
new_salary = salary*1.05 #Increase salary by 5%
Multi-line Comments
Python doesn’t provide any unique way for multi-line comments. However, any string can be used as a comment in Python, as long as it is not assigned to a variable. Python interpreter ignores such strings.
Code
"This line will be ignored"
print("Pylenin loves Python")
"""
Bigger comments can be written
over multiple lines.
This is a multi-line comment.
"""
print("Pylenin loves Python")
Run the above code and you will see that no errors are raised by Python.
Docstrings
Docstrings are not similar to comments. However, they have a similar purpose.
A docstring is short for documentation string.
Python docstrings are the string literals that appear right after the definition of a function, method, class, or module. They are used to provide a meaningful description of the above-mentioned objects.
Use triple quotes to write docstrings.
Code
def addition(x,y):
"""Takes x and y and returns their sum"""
return x+y
print(addition.__doc__)
Output
Takes x and y and returns their sum
You can also use Docstrings in a Python class.
Code
class Person:
"""Stores the name, age and country of a person"""
def __init__(self, name, age, country):
self.name = name
self.age = age
self.country = country
print(Person.__doc__)
Output
Stores the name, age and country of a person
Where to use comments and Docstrings?
Use comments to describe ambiguous logic and algorithms.
Use docstrings to provide information about Python objects like functions and classes in your code.
Good comments vs Bad Comments in Python
While a comment can really boost the understanding of a code, it can also ruin the overall developer experience and make things more ambiguous.
It is necessary to follow the best practices while using comments in your Python code to make your code more Pythonic.
- Write your comments in the imperative present tense.
- You don't have to explain every line of code.
- Incomplete functionalities in your code should always be commented.
- If you have copied a part of your code, mention the original source in the comments.