Understanding the Concept of Comment in Python

When writing program, it is important to make sure your code is easy to understand. Most times, the source code gets bulky and difficult to read or maintain in the future.

In order to curb this and increase the readability of your code, you need to add comments to your source code. This will help people using your code to understand what each area or part of your code represents and give future developers a clue on how to maintain the code.

In this article, I will explain the concept of comments, it's types, and why it is important to add comments to your code.

Let's get to it, shall we?

What are Comments?

Comments are text notes added to a program while coding to provide explanatory information about the source code being written.

They are added with the purpose of making the source code easier for laymen to understand, it also helps the maintenance of code. Comments are generally ignored by compilers as they are considered non-executable statements.

Types of comments

Using Python as a case study, there are two types of comments.

1. Single-line comment
2. Multi-lines or Doc-string comments.

Single-line comments

Single-line comments are created at the beginning of the line with the hash (#) character, they are automatically terminated by the end of the line. This type of comment can be added in-between lines of code to explain what a particular function is doing. As shown in the snippet below.

#this is a single line comment

# this is a python code
age = 26
if age <= 18: #condition
    print("still a teenage")
else:
    print ("you are an adult")

Multi-line Comment

In python, multi-line comments are created by adding three quotations (" " ") at the beginning and at the end of the comment or by adding the hash (#) character at the beginning of each comment line. It is used to explain things in a more detailed way and it is also used for documentation.

this is a multi-line comment sample 
where you can write all your code documentation
this is another comment line

For example,

''' this program will allow user to enter a number 
and will check if the number is an armstrong number.
an armstrong number is a number such that the sum of the nth power of its digit is equal 
to the number itself. where n is the number of digits in the number.
when a user input the number, the program check if the number is an armstrong number and 
print 'this is an armstrong number' otherwise 'this is not an armstrong number' is then printed '''
def armstrong_num():
    num = int(input("Enter your number: "))
    n = len(str(num))
    sum = 0
    if len(str(num)) == 1:
        print("All single numbers are Armstrong numbers")
    else:
        for a in str(num):
            sum += int(a)**n

        if sum == num:
            print("This is an armstrong number")
        else:
            print("This is not an armstrong number")

armstrong_num()

As shown in the example above, the function of the program and the expected output has been clearly stated in the multi-line comment section, which will give any other person that wants to work on the project clear understanding. However, there is another that can be done, and it is otherwise known as "block comment". this type of comments takes the hash(#) character for multiple lines an example is shown below:

# ''' this program will allow user to enter a number
# and will check if the number is an armstrong number.
# an armstrong number is a number such that the sum of the nth power of its digit is equal
# to the number itself. where n is the number of digits in the number.
# when a user input the number, the program check if the number is an armstrong number and
# print 'this is an armstrong number' otherwise 'this is not an armstrong number' is then printed '''
# def armstrong_num():
#     num = int(input("Enter your number: "))
#     n = len(str(num))
#     sum = 0
#     if len(str(num)) == 1:
#         print("All single numbers are Armstrong numbers")
#     else:
#         for a in str(num):
#             sum += int(a)**n
# 
#         if sum == num:
#             print("This is an armstrong number")
#         else:
#             print("This is not an armstrong number")
# 
# armstrong_num()

Here, there is a hash(#) character at the beginning of every line which makes the whole lines of code to be a block line comment.

Importance of comment(s) in programming

The necessity of documentation can't be overemphasized. As a programmer, you have to make your code readable and easy to understand, that is why adding a comment line to code is very important. These are some notable importance:

• It helps newbies to understand what the code is about and improve on his/her coding ability: for someone that does not know anything about coding he/she finds it easy to navigate around source code with a comment(s) because it explains what the code is about. As a newbie in Python, but tend to understand source codes with comments more than source codes without comments.

• It helps improve the open-source community because It makes it easier for the other programmer to understand the code and to know where improvement(s) is needed when they want to contribute to an open-source organization.

It is really important to keep your comment clear and explanatory. The main purpose is to save time and energy for maintenance and for developers who will want to work on the code.

Yes, we made it through! I'm sure you now understand the purpose of adding comments to your code, right? thumbs up!

I hope you find this article helpful. Feel free to drop your comment.