Using comments in Python 3

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.

1. 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.
2. 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.

1. Describe the intent and functionality of your code.
2. Help fellow developers understand your work and provide better code reviews.
3. Easier to remember the logic or algorithm behind a function or class

In Python, you can write comments in 3 different ways.

1. Single line Comments
2. Multi-line Comments
3. Docstrings

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.

1. Write your comments in the imperative present tense.
2. You don't have to explain every line of code.
3. Incomplete functionalities in your code should always be commented.
4. If you have copied a part of your code, mention the original source in the comments.