Types of Comments in Python
Developers often make use of the comment system as, without the use of it, things can get confusing real fast. Comments are helpful information that the developers provide to make the reader understand the source code. It explains the logic or a part of it used in the code. Comments are usually helpful to someone maintaining or enhancing your code when you are no longer around to answer questions about it. These are often cited as useful programming convention that does not take part in the program’s output but improves the readability of the whole program. There are two types of comments in Python:
Single Line Comments
Python single-line comment starts with a hashtag symbol with no white spaces (#) and lasts till the end of the line. If the comment exceeds one line, put a hashtag on the following line and continue the comment. Python’s single-line comments help supply short explanations for variables, function declarations, and expressions. For example, see the following code snippet demonstrating single line comment:
# This is a block comment
# Print "Co-learning Lounge !"" to console
print("Co-learning Lounge") # This is an inline comment
"""
output:
Co-learning Lounge
"""
a, b = 1, 3 # Declaring two integers sum = a + b # adding two integers print(sum) # displaying the output """ output: 4 """
Multi-line string as a comment
Python, by default, doesn’t support multi-line comments blocks out of the box. The recommended way to comment out multiple lines of code in Python is to use consecutive statements starting with #.
# This would be a multiline comment in Python that
# spans several lines and describes Co-learning Lounge.
# A tech communities for everyone. It contains
# well written, well thought
# and well-explained computer science
# and programming articles,
# quizzes and more.
print("Co-learning Lounge")
"""
output:
Co-learning Lounge
"""
But usually, that can be time-consuming and error prone, So another way to do this might be to enclose a piece of text in a delimiter “”” on each end of the comment.
Again there should be no white space between delimiter “””. They are helpful when the comment text does not fit into one line; therefore needs to span across lines. Multi-line comments or paragraphs serve as documentation for others reading your code. See the following code snippet demonstrating multi-line comment:
"""
This would be a multiline comment in Python that
spans several lines and describes Co-learning Lounge.
A tech communities for everyone It contains
well written, well thought
and well-explained computer science
and programming articles,
quizzes and more.
"""
print("Co-learning Lounge")
"""
output:
Co-learning Lounge
"""
# it is necesary to mention three quotes else it would throw an error
""
This would be a multiline comment in Python that # it is underlined red as it is throwing an error
spans several lines and describes Co-learning Lounge.
A Computer Science portal for nerds. It contains
well written, well thought
and well-explained computer science
and programming articles,
quizzes and more.
""
print("Co-learning Lounge")
"""
output:
File "<ipython-input-5-25958377ae31>", line 4
This would be a multiline comment in Python that # it is marked red as it is throwing an error
^
SyntaxError: invalid syntax
"""
# You can also use three single invested commas
'''This notebook on Co-learning Lounge gives you a
perfect example of
multi-line comments'''
print("Co-learning Lounge")
"""
output:
Co-learning Lounge
"""
Docstrings in Python
Functional programming is a way to write code for creating clean and maintainable software. Generally, functional programming means using functions to the best effect for creating clean and maintainable software. However, when we have multiple functions, it gets an uphill struggle to remember what each function does. Hence documenting each function is a good practice.
Docstring is short for documentation string. They are the string literals that appear right after the definition of a function, method, class, or module. Triple quotes are used while creating docstrings. For example:
def square(num): """Function to square the number""" return num * num
Docstrings appear right after the definition of a function, class, or module. This separates docstrings from multiline comments using triple quotes.
The docstrings are associated with the object as their doc attribute.
So, we can access the docstrings of the above function with the following lines of code:
print(square.__doc__) """ output: Function to square the number """
While learning Python, it is good to have a grip over comments, and we should implement them right from the beginning of our journey. Your code should be clean and descriptive. There is one quote by a legend I always remember “Always code as if the person who ends up maintaining your code is a violent psychopath who knows where you live.” 🙂