Comments in Python

Python / By

Comments are descriptions that help programmers better understand the program’s intent and functionality.

The Python interpreter completely ignores them.

  • Python code can be explained using comments.
  • Comments can be used to improve the readability of the code.
  • When testing code, comments can be used to prevent execution.

Advantages of Comments 

The use of comments in programs improves the readability of our code. It improves the readability of the program and helps us remember why certain blocks of code were written.

Aside from that, comments can be used to ignore certain code while testing other blocks of code. This provides a simple way to prevent the execution of certain lines or to quickly write pseudo-code for the program.

Python comments are classified into three types:

  • Single line Comments
  • Multiline Comments
  • Docstring Comments

Single line Comments

Single-line comments in Python have proven to be useful for providing concise descriptions of parameters, function definitions, and expressions.

To write a single-line comment in Python, use the hash symbol (#) with no white space and continues until the end of the line. If the comment continues to the next line, add a hashtag and resume the conversation.

Example1

# Print the string
print("Good Morning Everyone !!! This is Admin, Hello this is PythonPrograms")

Output:

Good Morning Everyone !!! This is Admin, Hello this is PythonPrograms

Explanation

Here the "Print the string" is the comment. 
The Python interpreter ignores this line.

Everything following # is ignored. As a result, we can write the above program in a single line as shown below:

Example2

print("Good Morning Everyone !!! This is Admin, Hello this is PythonPrograms") # Print the string

Output:

Good Morning Everyone !!! This is Admin, Hello this is PythonPrograms

Explanation

Here it will produce the same results as Example1. 
All the text following (#) is ignored by the interpreter.

Multiline Comments

Multiline comments are not supported in Python. However, there are other methods for writing multiline comments.

  • Writing multiline comments using Multiple Hashtags (#)
  • Writing multiline comments using String Literals

Writing multiline comments using Multiple Hashtags (#):

In Python, we can use multiple hashtags (#) to write multiline comments. Every line will be treated as a single-line comment.

# This is an example for writting multiline comments
# in python using multiple hashtags(#)
print("Good Morning Everyone !!! This is Admin, Hello this is PythonPrograms")

Output:

Good Morning Everyone !!! This is Admin, Hello this is PythonPrograms

Writing multiline comments using String Literals:

Python ignores string literals that are not assigned to a variable, so we can use them as comments.

Example1

# Good Morning Everyone !!! This is Admin, Hello this is PythonPrograms
'Writing multiline comments using String Literals'

Explanation

The second line of the code is a string, but it is not assigned to any
variable or function. As a result, the interpreter ignores the string.

Similarly, we can write multiline comments using multiline strings (triple quotes).

( ‘ )or ( ” ) symbols can be used as the quotation character.

Example2

'''

This is an example for writting multiline comments
in python using string literals

'''
print("Good Morning Everyone !!! This is Admin, Hello this is PythonPrograms")

Output:

Good Morning Everyone !!! This is Admin, Hello this is PythonPrograms

Explanation

The interpreter ignores the multiline string because it is not 
assigned to any variable. It is technically not a multiline comment, 
but it can be used as one.

Python Docstring

Python docstrings are the strings enclosed in triple quotes that appear immediately after the defined function. It’s intended to link documentation created for Python modules, methods, classes, and functions. It is placed immediately beneath the function, module, or class to explain what they do. Using the __doc__ attribute, the docstring is then easily accessible in Python.

A documentation string is a string literal used as the first lines of a code block, such as a function.

A documentation string, unlike a regular comment, can be accessed at runtime via the obj.__doc__ attribute, where obj is the name of the function.

Typically, a documentation string is used to generate code documentation automatically.

Docstrings are documentation strings.

Docstrings are not, strictly speaking, comments. They define anonymous variables that contain references to the strings. They are also not ignored by the Python interpreter.

Python has two types of docstrings:

  • One-line docstrings
  • Multi-line docstrings

One-line docstrings:

A one-line docstring, as the name implies, fits one line. A one-line docstring starts with triple quotes (“””) and ends with triple quotes (“””). There will also be no blank lines before or after the one-line docstring.

Example

def add(x, y):
    """Here it adds the x, y values and print the result"""
    return x+y


# Print the docstring of the above declared add() function 
print(add.__doc__)

Output:

Here it adds the x, y values and print the result

Multi-line docstrings:

A multi-line docstring, as compared to a one-line docstring, can span multiple lines. A multi-line docstring also begins with triple quotes (“””) and ends with triple quotes (“””).

Example

def add(x, y):
    """ Here we are writing the 
        multiline docstrings
        by writing the function that accepts 2 variables
        as arguments      
    """

How Can We Write More Effective Comments?

  • Use comments to describe what a function does rather than the specifics of how it does it.
  • Remove as many redundant comments as you can. Try writing code that can explain itself by using more descriptive function/variable names.
  • Make your comments as brief and concise as possible.