MAKING USE OF COMMENT AND DOCSTRINGS IN PYTHON3

COMMENTING IN PYTHON

What Is Commenting?

Commenting describes the functionality and explanation of your python code.

Reasons for using comments.

After knowing what a comment is, I guess you will be thinking about why we use it in our codes. Consider these scenarios.

1. You are working on a large team project where you need to collaborate with different developers to build and upon sending your code for review they don’t understand what each line of code works for because there are no comments, it will be unprofessional having to explain each line of code one after the other on a call.

2. You wrote a great stable application a few years ago, until yesterday! Yesterday, you want to add new features to your application to upgrade it. Unfortunately, one of the features broke and you don’t know where to make the changes to fix the features, as there are no comments and you can't remember what each function or class does over the years.

Comments and proper documentations are the only things capable of helping in such scenarios.

Here are some advantages of using the Python comments in our codes.

1. Describes the functionality and explain the usefulness of
your code.
2. Helps fellow developers understand your code easily and
provide better code reviews.
3. Easier for code debugging.

In Python, there are 3 different ways to write comments.

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

You will also learn about the Good comments vs Bad comments in Python.

Single-line Comments

You can use the hash symbol # to write single-line comments in Python. Everything after the hash symbol # will be considered a comment and will be ignored by the Python interpreter.

Code

# printing Your Name                          
Name = ‘Seyi Sennuga’
print(Name)
# checks if all Name are in capital letters
C_name = Name.isupper()
print(C_name)

If single-line comments are placed on the same line with a Python code, they are called Inline comments. Below is an example.

alpha = [17,119]
alpha[1]=90  #replace the 119 with 90
print(alpha)

Double-Line Comments

There is not much difference between the single-line comments and the double-line comments, just that you have to repeat the hash symbol # in the next line you want to write your comments to avoid too long comments in your code.

Code

# Write a menu-based program to insert, remove, sort,
#extend, reverse and traverse a list of items.
# Hint: Define functions to perform different operation
#of list, such as insertList() and removeList() etc.

mylist = ['Boy', 'Cat', 'Duck', 'Egg', 'Fish', 'Seyi']
mylist.remove('Cat') #removes specified (cat) elements in the list
print(mylist)

Multi-line Comments

Python doesn’t have any unique way for multi-line comments. However, any string can be used as a comment in Python, given that it is not assigned to a variable.

Code

''' This is also a comment
and is known as
a multi-line comment '''

'This can also be a comment'

"Another comment"

mylist = ['Boy', 'Cat', 'Duck', 'Egg', 'Fish', 'Seyi']
mylist.remove('Cat') #removes specified (cat) elements in the list
print(mylist)

Run the above code and it will run without any error from Python.

Docstrings

Docstrings are not similar to the normal comments. However, they have a similar purpose as comments.

A docstring is short for a documentation string.

Python docstrings are the string literals that appear right after the definition of a function, class, method, or module. They are used to provide a meaningful description of the above-mentioned objects.

Use triple quotes to write docstrings.

Code

def addition(a,b):
    """Takes a and b and returns their sum"""
    return a+b
print(addition.__doc__)

Output

Takes x and y and returns their sum

Where to use comments and Docstrings?

Use comments when you want 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 boost the understanding of a code, it can also ruin the overall developer experience and make things more difficult to understand.

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 source in the comments