How to Comment Code in Python

Steven RogerJuly 15, 2024

0 42 3 minutes read

Developers spend far more time reading code than developing it, making code readability a critical component of creating efficient and maintainable software solutions. Comments help to improve code readability.

Table of Contents

What is a Comment?

A comment is a piece of text included in code that describes what the code performs. It could be an explanation for other programmers reading the code or a note for future reference. Comments are disregarded by compilers and interpreters, and hence have no influence on code execution.

Although Python is a fairly intuitive language with an easy-to-understand syntax, programmers sometimes include comments in some portions of their code. In this article, we’ll look at why comments could be important and how to remark in Python. We’ll also go over several situations in which remarks are unhelpful and should be avoided. Before we get into how and when to make comments, let’s first learn about the various comment kinds in Python. Check out our free Python course online to learn more about Comments.

Types of Python Comments

Single-Line Comments

There are several ways to write Python comments. The format of a comment is determined by the length of the comment and the programmer’s preferences.

Comments begin with a hash symbol (#) and one whitespace character. In the example above, the text after the hash mark is a remark that describes what the code in the following line does. This is an example of a single line comment.

In-line Comments

We can also write comments on the same line as a statement, as per the code. These are known as inline comments, and they begin with a hash mark followed by a single whitespace.

Multi-line Comments

In rare circumstances, a comment is too long to fit on one line and must be split across many lines. These are known as multi-line comments. We can create multi-line comments in two methods. The first method is to use multiple-line strings. The interpreter ignores multi-line texts that are not assigned to a variable, allowing them to be used as comments. The alternative option is to use comments that span many lines, each of which begins with a hash mark.

When to Use Comments

We studied numerous approaches to write Python comments. Now let’s talk about when it’s appropriate to include comments in our script. We’ll look at various examples of how a comment might help you write clean code.

Informative Comments

Informative comments are used to describe what a complex piece of code performs. Programmers consider adding comments where they believe it will be difficult for outsiders to understand the code. A common use case is providing a remark that describes what a regex (i.e. regular expression) matches, which might be extremely complex and require people to conduct additional study to comprehend.

If you are unfamiliar with regular expressions, you will need to spend a significant amount of time determining what the regex pattern in this example matches. Furthermore, unless the code is intended to teach someone regex patterns, what’s the sense in making them work so hard to grasp it? They can simply read the comment and continue with the rest of the script. This is an excellent example of how valuable and functional a comment can be.

Legal Comments

In some circumstances, comments are required for legal reasons (such as providing copyright information).

Explanation of intent

In some circumstances, explaining the goal can assist other developers understand why you wrote a piece of code the way you did.

Commenting Out Code for Debugging

We said that the interpreter and compiler disregard comments. So, when we’re troubleshooting a script or looking for a bottleneck creating performance issues, we may comment out a section of code and continue running the rest. If the error or performance issue is fixed after commenting out a certain area of the script, we can infer the commented-out part is problematic—or at least examine further into the commented-out part to find the exact issue.

Bad Comments

We should avoid using comments to explain poorly designed code. It is better to avoid using comments unless absolutely required. If you believe your code requires comments, try rewriting it so that it is clear and comments are unneeded.

We previously explained that we sometimes comment out a portion of code for debugging. After this procedure is complete, we may wind up with code that is no longer required. In such circumstances, we should not treat it as commented-out code. Instead, we should remove that line of code to keep the script cleaner and more readable. Since practically all codebases are controlled with a version control system (e.g., Git), we can always revert to another version if a commented-out piece of code is ever required again.

It’s critical to maintain comments up to date when the code changes. Otherwise, they will cause more harm than good and be misleading.

We should avoid utilising comments when they are not required. Comments have no impact on code execution because the compiler and interpreter ignore them. However, they are an essential component of code readability. We must use them properly as a tool to increase instructive power.