Python Comments


Python Comments

Whenever we write any code, we may want to explain some complex logic in plain English. We accomplish this with the help of comments. Comments are the non-executable lines we write in our program to explain the code. Comments are also used if we want to prevent a few lines of code from executing.

In Python, comments are written using the hash(#) symbol.

Python Comments

Single line Comment

For the single-line comment, we simply have to use the hash(#) symbol.

When the comment is written on the same line as the statement, then that comments are known as inline comments.

Shortcut: ctrl + /

In the windows operating system, we can use the shortcut ctrl + / (i.e. control + forward slash) to comment or uncomment any line.

Single line comment

In [1]:
a = 5
b = 20

# adding a and b
c = a + b
print(c)

Comment to prevent execution of code. We have commented line c = c/10.

In [2]:
a = 5
b = 20

# adding a and b
c = a + b
#c = c/10
print(c)

Inline comment

In [3]:
a = 5
b = 20


c = a + b # adding a and b
print(c)

Multi line Comment

There are two ways we can add multi-line comments:

  1. Using the hash(#) symbol in front of each line.
  2. Use the triple double quotes(“””) or triple single quotes(”’) at the beginning and end of the comment. This is the most commonly used method.

Multiline comment.

In [1]:
a = 5
b = 21
# This is example of multiline comment.
# We are doing b mod a here.
# It will return the remainder.
c = b%a
print(c)
1

Multiline comment using triple quotes.

In [2]:
a = 5
b = 21
"""
This is example of multiline comment.
We are doing b mod a here.
It will return the remainder.
"""
c = b%a
print(c)
1

Docstrings

A docstring or a documentation string, is a string literal that occurs as the first statement in a function, class, or method definition to provide documentation. Docstrings are primarily used to describe the purpose, usage, arguments, return value and behavior of the code they document.

In Python, a docstring is typically enclosed in triple quotes (”’ or “””) and is placed immediately following the definition header.

We can view the content of the docstring by passing the name of the function to help.

Multiline comment in function. It is considered as a docstring.

In [1]:
def func_mod(a,b):
    """
    This is example of doc string.
    We are doing b mod a here.
    It will return the remainder.
    """
    c = b%a
    print(c)

func_mod(5,21)
1

We can use help() function to see the docstring.

In [2]:
help(func_mod)
Help on function func_mod in module __main__:

func_mod(a, b)
    This is example of doc string.
    We are doing b mod a here.
    It will return the remainder.

We can also see the docstring using __doc__ attribute.

In [3]:
print(func_mod.__doc__)
    This is example of doc string.
    We are doing b mod a here.
    It will return the remainder.
    

Advantages/Uses of Comments

There are a number of benefits of good comments. Let us understand them one by one:

  1. Explanations: Comments are used to provide details about the purpose of a particular section of code to describe it to other developers and for the purpose of documentation.
  2. To-dos: We can mark sections of code where additional work is needed. It is always better that TODO comments start with “TODO” for convenience
  3. Debugging: We can temporarily comment out code during debugging. Add comments to explain debugging steps or breakpoints.
  4. Documentation: To include information that can help other developers understand your code when they collaborate on the project. Mention dependencies, assumptions, or special considerations.
Advantages/Uses of Comments

Resources

Handwritten Notes

References:

  1. Python Comments
  2. Types of Comments
  3. Uses of Comments