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? However, they do not have any effect on the logic of the code as they are completely ignored by the interpreter.

Using comments in Python or any other programming language is a very good practice. Not only do 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. To add 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?

The project is mostly divided between developers, who 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 when 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 another developer is hired. After some time, the client wants some changes to 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. However, because the previous developer has not written comments about the mindset behind a particular code and what a particular function is going to do, how would someone new know about it and 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 easy for the new developer to understand and work on the code.

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.