Introduction

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.

The developers 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 like what a given a variable is doing, how a function is working and so on.

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

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. This review of code is what takes - in fact, what wastes - time.

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

What are comments?

In programming,

Comments are statements ignored during the execution of a program.

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 can 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.

General rules of commenting

Knowing what commenting is doesn't necessarily tell one how to comment. Commenting just like variable naming is another art that comes with experience, time and skill.

As you begin commenting your code, you may do it unnecessarily, 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 suggestions 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.

In this case, the example might not look that weird but if you type the code above in your IDE where the code editor covers the whole screen, you'll find the comment extending out till the end of the screen, and looking extremely awful!

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)

Comments don't always have to be in perfect grammar

All those who love perfect grammar, behold, comments hate perfect grammar.

While writing comments it's easy to get stuck in the precisions of grammar, such as giving commas, capitalising words after a dot and so on. Comments are not part of any exam of any one of us - they are there to explain a piece of code, that's it.

If you're saying something in three lines in the best ever grammar on Earth, which could be said in one single line in poor grammar, programming urges you to switch your style!

Let's consider a quick example.

# add x and y
# print the result

x = 10
y = 5

print(x + y)

In the code above we comment out the purpose of the whole code at the start in perfect grammar:

In contrast, below we write the same comment by dropping some words in it.

# add x and y
# print result

x = 10
y = 5

print(x + y)

As you can read here, the meaning of the comment has not been modified in any way. It definitely is grammatically incorrect to say 'print result' but not meaningless - one can rightaway understand that we are printing the result.

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(x + y) # print the sum of x and y

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

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, contributing considerably to code clutter.

Consider the example below:

import math

num = math.factorial(100) # compute 100!
num = str(num) # convert to string
The statement import math serves to import the math module from Python's standard library. We'll learn more about the import keyword and modules in detail in the Python Modules unit.

Here we put a comment after both the statements in line 1 and 2. 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 string
num = str(num)

This time, both the comments precede the statements they explain. Furthermore, the second comment leaves whitespace above it to help distinguish the fact that it explains line 7 in the code, not line 4.

Moving on

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.