Python Comments

Developers often write programs and leave them for a while as they work on a different project, or as they go out on a vacation. Now when they come back to resume development of those programs, a lot of time is wasted in understanding what's going on.

They couldn't understand what's happening in their own code.

But why?

We as humans tend to forget things with the passage of time. It's a natural process, that happens with everyone, including developers. When they're writing a program, at that moment they know everything about it, such as what a given variable is doing, how a function is working, how is a list being used in the loop and so on.

However, once they come back after a long time and look over the code, all this knowledge is lost.

This means that they have to literally go line by line from the very start to the very end of the program until they can fully understand what's going on. Worse yet, sometimes, they couldn't understand what's going on, completely.

This review of code is what takes — in fact, wastes — time.

Is there some way to overcome this? Surely — use comments!

In programming,

Comments are not used by machines for any purpose; they are just meant to be used by humans.

In Python, a comment is denoted using the # hash symbol. The line following the hash symbol is a comment.

Below shown is a comment:

# this is a comment

Such types of comments are more specifically known as single-line comments, since they span only a single line.

The comment can be as long as possible, given that it is one single line. Breaking a single-line comment into multiple lines is invalid.

Consider the code below:

# this is a comment
and this is a comment as well

Line 1 is a comment, however line 2 is not. Python only considers the line following the hash symbol as a comment and likewise treats just line 1 as a comment, while line 2 is considered as Python code. Since line 2 is invalid Python code, we get an error.

Unlike languages such as PHP and JavaScript, Python only supports single-line comments.

To write a comment block that spans multiple lines, we have to use a hash symbol at the start of each line.

In this way, each line becomes a separate comment, however when we read them all together, they seem as one single comment block.

# This is how we can write
# a long comment and then break
# it down into multiple lines

As you begin to write comments in your code, you may do it unnecessarily sometimes, or construct extremely long and difficult-to-understand comments.

But don't worry — this is what all of us do in the beginning. With time, we learn the discipline and trick to commenting briefly, yet meaningfully.

Below are a couple of tips to consider as you comment out your code.

Break long comments into multiple lines.

Writing long comments is not something surprising in complex applications. Sometimes even in the simplest applications, a short brief license notice, or copyright disclaimer put at the top is considerably long.

Putting long comments on one single line is not syntactically invalid - just visually undesirable.

Let's see how. Below we construct a really long comment that spans a single line.

# This is a long long long comment that takes a long long span of words which is undesirable in Python and all programming languages.

x = 10
print(x)

See how the comment unnecessarily acts as a divider in the code rather than documenting it. It distracts our reading flow on the code, and seems as if it's not part of the code.

Once again, it's not undesirable to write long comments in Python - well sometimes, it is - it's just undesirable to write them on one line.

What one should do is break the comments into multiple lines, each one a comment on its own.

The comment above can be rewritten in the following way:

# This is a long long long comment that takes
# a long long span of words which is undesirable
# in Python and all programming languages.

x = 10
print(x)

Isn't this more readable?

A good question at this point might be: when to break a comment into the next line?

Well, a good rule of thumb is to break right after 80 characters (including the # at the start of the comment). This is quite a standard convention used in numerous coding environments, which not just applies to comments but also to any arbitary statement.

Give comments above statements

When commenting, it's desirable to put the comments above statements as compared to putting them next to statements.

Writing comments next to statements reduces the readability of code and gives us very little room to express ourselves.

Consider the code below:

import math

num = math.factorial(100) # Compute 100!
num = str(num) # Convert to a string

Here we put a comment after both the statements in line 3 and 4. See how the comments reduce the readability of code.

Now, let's change the location of these comments and review the code:

import math

# Compute 100!
num = math.factorial(100)

# Convert to a string
num = str(num)

This time, both the comments precede the statements they explain. Furthermore, the blank line before the second comment helps to distinguish the fact that it explains line 7 in the code, not line 4.

Don't comment everything

Remember: less is more!

Only comment those parts of a program that involve something that's not apparent — something that would be difficult to understand later on.

Commenting redundant pieces of code as shown below is useless:

x = 10
y = 5

# Print the sum of x and y.
print(x + y)

In line 4, we can easily realize that we are printing the sum of x and y, and so the comment is more than just useless.

Throughout this course, wherever we want to show the output of a print() statement, without giving a separate shell snippet for it, we'd simly put a comment next to it showing the output.

An example follows:

print(10 + 5) # 15

Keeping in mind these simple guidelines, you're good to go to comment out your code.

Sometimes scripts will be so simple that a single comment at the top of the script will do the job. However, sometimes and usually in most cases, scripts will be complex and likewise different segments of code will require careful and meaningful comments.

From now on, we'll use comments in our scripts where ever we wish to explain a given set of statements to you. In this way, you'll not only understand those bunch of statements, but also how commenting plays a crucial role in program development.