Python Comments

Introduction to Python Comments

The primary purposes of using comments in Python are:

• Comments are used to describe the code. Adding comments to the code makes it more human-readable and makes it easy to maintain the code.
• Testing the code
• Comments can be used as documentation, meaning they can be used to explain the code or Metadata of the project
• We can use comments to prevent the execution of specific code blocks.

For example, let’s say you have written complex business logic, formulas, algorithms, etc. Then we need to document it using the comments that explain what the code does, thus improving the readability of the code in Python.

Python interpreter ignores the comments while executing the code and only interprets the code.

Types of comments in Python

There are three kinds of comments we can use in Python.

• Single-line comments
• Multi-line comments
• Documentation strings, aka docstrings

Let us look into details on how to use these comments in Python code with examples.

Single-line comments

Single-line comments start with a hash sign # followed by a single space and a text string. The hash # works with only a single line of code, and any code that comes after a hash # will be ignored and not executed.

Single-line comments are mainly used to describe the line of code; it is placed either before the line of code or after the line of code.

Let’s take an example to demonstrate single-line comments in Python.

Example of Single-line comment in Python

# This is a single-line comment example

print("Hello World") 

Inline comments

If you place the comment in the same line as a statement, you will have an inline comment.

Like single-line comments, inline comments begin with a hash (#) sign and are followed by a space and the comment text. Any code that comes after a hash # will be ignored and not executed.

Let’s take an example to demonstrate inline comments in Python.

a = 4
b = 5
sum = a + b  # Calculate the sum of a and b
print(sum) # Print the Sum of a and b
print("Hello World")  # This is an example of an inline comment

Multi-line comments

Usually, in other languages like Go, C, C#, Java, etc., we can write a multi-line comment, as shown below.

/* This is an example of 
multi-line comment in Go lang */

Like other programming languages Python, do not have Multi-line comments.

**Python may not have any built-in mechanism for commenting out multiple lines. However, there are different ways to achieve this in Python. **

Using Hash in each line (#)

We can use multiple hash # to write multi-line comments in Python. Each line with a hash sign (#) is considered a single-line comment. Hence we can use hash in each line that we need to comment.

Multi-line comments Example

# This is how we can achieve 
# Multi-line comments in Python
print("Hello World")

Python docstrings

Documentation strings, also called docstrings, are the string literal denoted with triple quotes that occur as the first statement in a module, function, class, or method definition. Conventions for writing good documentation strings (a.k.a. "docstrings") are immortalized in PEP 257.

Note: We can also use triple """ quotations to create docstrings.

Single-line docstrings

Let’s take an example to demonstrate single-line docstring.

def Add(a,b):
    '''Takes two numbers as input and returns the sum of 2 numbers'''
    return a+b

Inside the triple quotation marks is the docstring of the function Add(), which appears right after its definition.

Multi-line docstrings

The multi-line docstring can span across multiple lines of code, starts with triple quotes("""), and ends with triple quotes (""").

We can use multi-line docstring as multi-line comments in Python to comment out a block of code.

The following example shows you how to use multi-line docstrings. Make sure to indent the leading ''' appropriately to avoid an IndentationError

Multi-line docstring example

def Add(a, b):
    """Takes two numbers as input
    Adds a and b
    Returns the sum of a and b as output
    """
    return a + b

print(Add(5, 6))

Note: As long as the string is not assigned to any Python variable, Python will read the code but then ignore it, and you have made a multi-line comment.

Best Practices for writing code comments

• Do not duplicate the code while explaining the code in comment blocks.
• Write precise and meaningful comments. Do not provide a detailed explanation and clarification of the code.
• Do not comment out the actual code; if a piece of code is not in use, it is better to delete it rather than comment it out for future use.
• Add Metadata and document style commenting, which provides an overview of the code, class, methods, parameters, and the return type.
• Provide links to external references if you have referred the code from online sources.
• Add the comments while fixing the bugs
• Do not overdo it