* 4 min read

A comment on the uses of comments

In coding, comments are simply lines of code that are ignored by the interpreter or compiler during execution of the program. They exist for several reasons.

Comments drastically improve the readability of the code

Say you wrote a large multi-function code that contains many different functions and variables, a long while back. You now come back to this code and need to use it. But the problem is that you have no idea which function does what, and the variables are confusing. You can’t follow the code. It is confusing and difficult to read.¬†Well, this is where comments come in very handy. Comments are used to help you easily read every chunk of your code, so you can easily follow the flow and steps of the code. This is extremely useful for long programs, and would save you a great deal of time. Writing brief, concise comments go a long way to remember certain parts of the code or even to add small reminders about certain functionality.

Comments helps other developers to understand your code

Comments are also a great way to help other developers to easily read and understand the code before they make changes to it. Since these guys were not with you when you wrote the code, they have no idea about it. So you would do them a favor and save them time and headache by simply adding easy-to-follow comments for each block of code. They will thank you for that these small explanations, which will help to increase the overall readability of the code.

Comments can be used to stop certain parts of the code from executing

Comments can be written to stop certain parts of the code from running during testing/debugging. Sometimes you want to prevent certain lines of code from running, in order to test a new line. Then you can choose which works best. But you don’t want to completely delete the first line when testing the new line. So the best way to do this is to comment out the original line.

 

Types of comments in Python and their syntax

There are generally two main types of comments in Python, namely, single-line comments and multi-line comments.

Python single-line comment syntax

A single-line comments can be written on a line on its own. This is usually used to explain the block of code that follows, in order to make it easier for you, and for others, to better comprehend the code. It is simply written as a hash character, followed by a space, and your comment or explanation. This will not run during execution of the code.

# This is a comment in Python. It won't ever run. 
print("Hey, world!")

A single-line comment can also be used after a line of code, on the same line as the code itself. This is helpful to add comments for one line of code at a time. This can be done like so:

 
print("Hey, world!") # This is a comment on the same line as the runnable code. 

A single-line comment in Python can be used to prevent certain lines of code from running during execution. This is extremely helpful during testing.

 
# print("Hey, world!") 
print("Let's just print this for now, and ignore the rest of the code!") 

Python multi-line comment syntax

A multi-line code in Python is usually used for documentation purposes by developers. It can also be used in the beginning of the code to explain the main functionality of the code, what it does, a copyright, the name and contact details of the developer, and usually a license. It can also be used to provide more detailed explanations for more complex chunks of code. A multi-line comment can be written in two ways. The first is to simply use a bunch of lines that start with the hash symbol, as follows:

 
# This is a multi-line comment
# The main purpose is to provide more details for more complex blocks of code.
# Easy, right?
print("Hey, world!") 

You can also highlight the text and use the keyboard shortcut (Windows)  ctrl + 1 to automatically do this.

 
#This comment was automatically created by writing the text and then 
#just highlighting the entire block of text and  ctrl + 1. 

Another way to add this, but with also adding a top and bottom border to the text, is to use the keyboard shortcut ctrl + 4.

 
# =============================================================================
# This comment was automatically created by writing the text and then 
# just highlighting the entire block of text and  ctrl + 4. 
# =============================================================================

Another way to create a multi-line comments is to use triple quotes. This way is easier than the first, especially if the comment is very long, or if you want to edit out large blocks of code.

 
"""
This is also a multi-line comment, but rather thank using hash symbols, 
we can just use a triple quote at the beginning of the comment, 
and one after the comment ends. This is useful for lengthy comments. 
"""
print("Hey, world!") 

Conclusion

Learning to add comments to your Python code is vital to ensure the code is easily understood by others, including your own self when you want to come back and re-read the code. It will make everyone’s life easier and avoid wasting time. Adding brief, concise, straightforward comments along the way of writing your code will go a long way in the long term, will make it easier for other developers to collaborate with you, and will improve the overall readability of your code in general. Comments are always a good practice and you should definitely make it a habit of incorporating them into your code, especially if you are working with other coders.

 

1

Mohammad D.

Mohammad D. works with sentiment anlaysis, NLP and Python. He loves to blog about these and other related topics in his free time.
LinkedIn

Leave a Reply