This Python comment tutorial explains why are comments important and how to write single line, multiline and DocString comments in Python:
Programming is the way to train the computer like a human brain. Commenting in Python helps the developers to explain and describe the working of the code. If the developer does not write the comments in the code, then it will be difficult for any other person to know what these lines of code are doing in a program.
This process makes it easy to find out the bugs and resolve them and it becomes easy for the other person to continue working on the same code.
=> Read Through ALL Python Tutorials Here
Table of Contents:
Python Comments
No matter whether the code is long, medium, or small, commenting is important in all kinds of programming projects whether they are written in Java, Python, C/C++, etc.
The code with no comments becomes confusing for the developers and it takes a longer time to complete the work. It is the quality of a good developer to mention comments in the program.
In this tutorial, we will cover the basics of how to write comments in Python.
Why are Comments so Important
Comments are an essential part of every program. They can be available in the structure of docstrings or can be inline explanations that will help to learn the complex functions.
It makes the code readable and thereby helps the programmers to remember what they did in their past while working on any particular project. Let us take an example and understand why comments are important in code.
We are providing two scenarios in which the developers decided not to write the comments in the code.
Scenario 1: A developer reading his/her own written code.
Developer A is working on a project “ Project A ” and has to submit it on time. He is on a tight deadline and there’s no chance to increase the timeline. He finished his work successfully and submitted it on time before the deadline of the project.
But he left the documentation work including comments & manual of the project and thought of writing it later. On the next day of the deadline he gets another project “ Project B ” and starts working on that project. He completely forgot to write the documentation part of the previous project “ Project A ”.
Time flies and after 7 months, Client A needs modifications on “ Project A “ from Developer A. When Developer A started working on the same project, he was unable to figure out the entire code. He forgot what the code meant in his own program.
The above scenario would not have happened if Developer A would have commented on his code properly.
Scenario 2: When the other developers are trying to read your code.
Suppose you are working on a tiny project and you know very well what you have written in the project. In this situation, you didn’t write the comments in the code because you thought comments are needed. As we all know, writing comments need time.
But when the new developer has to continue the work on the same project, how would he/she understand the code?
The new developer has no idea on what is written in the code. In this scenario, it is clear that comments are very important in every code, regardless of whether it is a small project or a large project. They will help the new developers to continue the work on the same projects.
How to Write Comments in Python
Let us understand how to write the comments in the Python code with examples.
Basics of Comments in Python
Comments are written for the new developers who continue the project written by the other developers. They narrate the piece of code as required to explain the logic and program flow.
In Python hash mark “ # ” is used before the starting of the line of code to write a comment.
Example
``` # This is the comment in Python ```
Python will ignore the line of code that starts with a “ # ” hash mark. Developers can add the comment anywhere in the code.
Example
``` print( “ Welcome to the SoftwareTestingHelp Website ” ) # This is the first statement ```
After running the above code, you will see the output to be like “ Welcome to the SoftwareTestingHelp Website ”, the statement starting with “ # “ will be ignored.
Note: Comments should be small, polite, and to the point. The maximum length of the comment is 72 characters and if it exceeds the limit then, the user will need to divide the comment into multiple lines.
Types of Comments in Python
Single Line Comment
Python has a different way to write comments when compared to the other programming languages like C, Java, etc. In the Single Line Comment, only the hash marks “ # ” is used at the beginning of the line.
Example:
``` # This is the SIngle Line Comment Welcome to SoftwareTestingHelp Thanks! ```
In this example, the first line of the code will be ignored because it has “ # ” and the rest of the lines will generate a Syntax error because they are not valid Python statements and they are not commented either.
Multiline Comments in Python
Let’s compare the multi-line comment in Java with Python. You can understand it with an example:
Java Comment Example
``` /* This is the multiline Comment in Java Welcome to SoftwareTestingHelp Thanks */ ```
In Java, the multiline comment is written as shown above. “ /* ” is used to start the comment and “ /* ” is used to end the comment. The lines between the /* and */ will be ignored at the execution time of the program.
But Python does not support the native multiline comment as the other languages do. To create the multiline comment in Python, we have two ways:
- We can just add “ # ” at the starting of each line as shown below.
``` def demo(): # Welcome to SoftwareTestingHelp # Thanks ```
All the above lines that start with ” # “ will be ignored at the execution of the program. The above technique is called a block comment. Here, we use “ # ” at the beginning of each line to refer to it as a comment.
- Another way is to use “ “”” “ triple quotes at the beginning and end of the multiline comment as given below:
``` def demo(): “”” Welcome to SoftwareTestingHelp Thanks “”” ```
DocString Comment
Documentation Strings are the strings that are written within the double quotes (“”) or single quotes (‘‘) and act as comments in the program. These are basically used for the documentation part. In some functions or classes when we click or call them, then it will show its documentation.
Let us take the example
```
def demo():
"""
This function will take the input from the user and
print the factorial of a number.
If the input is negative than it will generate
an error.
"""
fact = 1
a = int(input("Enter the number"))
if a > 0:
print(" The number is greater than zero.", a)
for i in range (1, a+1):
fact = fact * i
print("The factorial of a given number is:", fact)
elif a == 0:
print("The factorial of a given number is: ", a)
else:
print("This number is not valid! Please enter the correct number")
demo()
```
Output
If we call the function “demo” with the “.__doc__” keyword, like “demo.__doc__” What will happen?
It will show the documentation of the function that we have written in the double quotes.
Difference Between DocString Comment and Comment
| DocString Comment | Comment |
|---|---|
| DocString is not omitted by the Python interpreter. | Comment is omitted by the interpreter. |
| It is used for the documentation. | It acts as the hint for the programmers to guide them what is happening in the code. |
| To access the documentation part “ ._doc_” keyword is used. | To access the comments programmers does not need any keyword. |
Polite Comments v/s Rude Comments
As we discussed above, the comments should be polite and small so that everyone can easily understand. But there can be a possibility of rude comments in the program. Polite Comments v/s Rude Comments.
Example:
``` def demo() a = 10 # Assigning the value of a b = 15 Sum = a +b # Calculating the sum of two numbers return Sum ```
In the above example, the comments are simple and easy to understand and look good.
Example:
``` def demo() a = 10 # Understand it and don’t make stupid mistakes while writing the code. b = 15 Sum = a +b return Sum ```
In the above example, the comment is so rude. It will demotivate the new developers before working on the new project.
Note: Always avoid rude comments.
Common Practices
It is common to start out a Python file with a couple of lines of comments. These lines describe the information regarding the project, the aim of the file, the programmer who developed it or has worked thereon, and the software license that’s used for the code.
The comment starts with the outline, and is followed by the copyright notice with the developer’s name, and therefore the year of publication of the specific code. The code is accredited under the GNU Public License (GPL).
Example:
Include the following format in each file of your project.
``` “”” < Brief description of the purpose of this file > Copyright 2021, Organization name Distributed under the terms of the GPL License. Author: Author name “”” ```
Comments that are included while creating a class or a function.
```
def demo():
"""
This function will take the input from the user and
print its table in range (0, 11).
If the user input is negative than it will generate
an error.
"""
a = int(input("Enter the number"))
if(a > 0):
print(" The number is greater than zero.", a)
for i in range (0,11):
print(a, 'x', i, '=', a * i)
else:
print("This number is not valid! Please enter the correct number")
demo()
```
Frequently Asked Questions
Q #1) How do you write comments in Python?
Answer: In Python, comments are used to describe the code that is written in the program. So that in the future, if any new developer wants to work on the same project, he/she will be able to understand the code with the help of comments mentioned in the program.
Comments are written using the hash mark (#) at the beginning of the line.
Example:
“`
# Welcome to the SoftwareTestingHelp!
“`
Q #2 ) How do you comment out multiple lines in Python?
Answer: In Python, to comment on the multiple lines of code in the program, the developer can use two ways as discussed above in this tutorial.
- Use a hash mark at the beginning of each line.
``` # This is the multiline comment in Python. # Using the hash mark in each line. ```
- Use triple quotes at the beginning and the end of the comment.
``` “”” This is the multiline comment in Python. Using the triple quotes. “”” ```
Q #3) What is the use of a comment in Python?
Answer: Comments are used to describe the logic of the code written in the program. Comments help the new users and the developers to understand the code and continue his/her work on the same project.
Q #4) How to block comments in Python?
Answer: In Python, block comments are used to describe the complex code. In the block comments, each line starts with the “ # ” hash mark at the beginning. If the developer wants to comment on one or two or more paragraphs, then they will be split by a line that has one hash mark.
Example
```
# In this program the function sum()
# will take the two integer values "a" and "b"
# and calculate the sum of two numbers
def sum():
a = int(input("Enter the number: "))
b = int(input("Enter the second number: "))
addition = a + b
print("Sum of the given two numbers = ", addition)
sum()
```
Conclusion
Comments are used to understand the code scripts. They are ignored by the interpreter during the execution of code. They are used to make the Python program code more readable and it will help the new developers to continue working on any project.
Also, remember that one of the best ways of learning how to code and comment better is by reading other people’s code and their comments written in the program.
In this tutorial, we learned:
- Introduction to the comments in Python
- Why are comments important
- How to write the comments in Python
- Types of comments in Python
=> Explore The FULL Python Tutorial Series Here