Python Comments - Making Code User Friendly

Coding is not easy and making that code easy to understand is a bigger challenge in itself. But python comments make that difficult task quite easy. Python comments are nothing but a simple description of what you were thinking while writing that piece of code. Basically what is your thought process, what concepts you are using in a very precise manner. But they do not have any effect on the logic of the code as they are completely ignored by the interpreter.

It is a very good practice to use comments in python or any other programming language. Not only they make the code more readable but also, they help in removing errors in the code and improving the code for the later stages of development.

Contents

Writing Comments in Python

In Python, we can write single-line comments and multi-line comments.

Single-line Python Comments

Adding comments to your code is no rocket science. For adding a single line python comment, we just have to put a “#” in front of them.

For example:

Multi-line Python Comments

There are two ways through which you can add multi-line comments in python.

Add ‘#’ in front of every python comment. For example-

2. Using Docstrings for python comment

Why use Comments in python?

Mostly the project is divided between developers and they all have different tasks. One developer creates a certain function and another function. So it python comments make it very easy for other developers to understand the code while they have to do something with the code like adding something to it.
Let’s take a sample case. Suppose in a company one developer is working on a code and not using comments. After completing that particular project, he leaves the company and some other developer is hired. After some time the client wants some changes in the project but the developer who created the code has already left the company and the responsibility is on the new developer to make changes in the code. But because the previous developer has not written comments about what was the mindset behind a particular code, what a particular function is going to do, how would someone new know about it and will ultimately end up wasting a lot of time on it. On the other hand, if that developer had used comments in the code it would have been very easy for the new developer to understand the code and work on it.

Tips while using Python Comments:

Writing a good comment is an art too. A good developer always knows how to write a comment that is not redundant, and precise because writing every detail about a function is only going to waste time. It should just be a high-level idea about the code. And the other code should be made more readable by using proper variable names, proper function names.

Sometimes what people think is that they are the only one who is going to read the code so why bother in writing a comment, but they don’t understand that they will only be making their own life easier. Like, some of the developers make use of comments by using them as pseudo code and to keep track of what is left in the program.

Why? This question should be answered by the comment instead of what or how.

Many good programmers using comments for the debugging process. The developers comment out the piece of code which they don’t want to use temporarily or to find the mistake.

Lets see an example of how comments can be useful in debugging or finding the errors in the code.

Here, the program would give an error. And to check the error, we could put comments on the if statements one by one and then we would get to know that error is due to the a/b as b=0 and this operation is not possible and we could make changes in the code according to that.

Must Read:

Where to comment:

Some programmers always ask this question – Where to put the comments? The answer to that question is to put Python Comments in the following three places: –

Header Comment– It should include the name of the creator and what is the purpose of the program.
Python Function Comment: This comment should describe the function and its role in the program.
Inline comments: When we are using an out of the box logic or concept we can put comments so that we don’t forget them afterwards.

Shortcut for commenting out a certain piece of code:

In some Python IDEs like Jupyter Notebook and Pycharm we can use ‘Ctrl +/’ to comment out a certain piece of code.

Conclusion

At last but not the least, while writing the code we should always keep in mind that the person who is going to read the code has very limited knowledge about the programming language and create python comments accordingly.