Python Comments

Introduction to Comments in Python

Facebook and Instagram comments are all the rage these days. We all write them, read them and look forward to receiving them on social media platforms. Well, the world of programming also isn’t far behind on this trend. Comments have a special place in programming. Often, good comments prove to prevent catastrophes. Similarly, bad comments can leave other programmers wondering about their wit’s end.

Let’s take a look at what a good comment and a bad comment looks like –

A bad comment can be any of these things –

• Over-commenting
• Lack of comments
• Misleading comments.

Here are some of them –

On the flip side, a good comment would look like this –

Via this comparison, you can clearly see which code is more readable, elegant, and helpful.

In this article today, we will be focussing on Comments in Python programming.

What are Comments in Python Used For?

Learning to write comments in Python is also a valuable skill. There are several reasons why comments in Python are used. Some of them are-

• Explaining the code.
• Making the code more readable.
• Preventing execution while testing code.

Different Types of Comments in Python

When we talk about Python comments, three main types come to mind. They are –

1. Single-Line Comments in Python

The single-line comments in Python are denoted by the hash symbol “#” and include no white spaces. As the name suggests, this kind of comment can only be one line long. They come in handy for small explanations and function declarations.

Check out the following example –

2. Multi-Line Comments in Python

Python does not have multi-line comments, but there are two ways we can achieve this –

• You can write “#” at the beginning of every line you wish to comment out. This stimulates multi-line comments in Python. Let’s take a look at how we do that –

• For including multi-line comments in Python, we make use of the delimiter ("""). The text to be commented on is enclosed within the delimiter. We mostly use multi-line comments when the text doesn’t fit in a single line or when the comment spans more than a few lines. The following code snippet shows how we make multi-line comments using the delimiter-

3. Docstring Comments in Python

Docstring is an in-built feature in Python and is usually associated with documentation in Python. They are added right below the functions, classes, or modules, and they describe what they do. In Python, Docstring is made available using the doc attribute.

The way to implement Docstring in a code is as follows –

The use of Docstring describes what the function does and gives the following output –

Advantages of Using Comments in Python

Consider a scenario where your senior developer has asked you to make some last-minute changes to a particular function in your code. You panic slightly because you don’t remember whether you added comments or not.

But once you open your codebase, you are relieved because Python comments saved you!

The benefits of comments in Python are endless; hence it's advisable to use comments in Python. Let’s take a look at some of them –

• Readability- Python comments greatly enhance the readability of the code. They make the code easy to understand, and there is no need to remember why you wrote a certain code block. So Python comments not only ensure ease when you go back to read your own code from 6 months ago but are also easy for other developers in understanding your code.
• Blocking out certain code- Blocking out code for testing or execution is another avenue where comments are widely used. So the next time you wish to test out some specific lines of code, you can always comment on the remaining ones.

How to Write Good Comments in Python?

Only writing comments is not enough. Writing feasible and efficient comments is the main objective. So here are some things you can keep in mind to get better at commenting in Python-

• Always use comments to describe what a code block does generically and not in specific detail.
• Write comments only where they are necessary. In other words, get rid of redundant comments that may clutter your codebase and cause confusion.
• Keep them short and simple. This ensures that anyone can read them quickly and not waste too much time trying to decipher them.

Avoid Worst Commenting Practices in Python

The comments in Python should follow certain standards to ensure the comments are Pythonic too.

Here are just a few of them –

• W.E.T. Comments- Always write D.R.Y. comments. The acronym D.R.Y. stands for “Don’t Repeat Yourself”. This makes sure that there is no repetition or redundancy. If a code is simple enough to understand from a glance, then it does not need a comment to describe it.
• Smelly Comments- Code smells are now a widely used term to indicate any red flags in your codebase. These red flags or flaws are usually related to readability, maintainability, and scalability issues. If your code is not up to the mark, then no amount of good commenting can save it. Comments should always support the code instead of explaining it in depth. Hence, always avoid smelly comments.
• Rude Comments- More often than not, all developers work in teams. So there might be instances where someone else might rectify or edit your code. Thus, comments should be polite and professional enough for a working environment.

Read More

• Type conversion in Python
• Comments in SQL