Comment in Python like a Senior Developer

Comments. Everyone’s heard of them but not everyone knows how to use them.

There is a general notion that “comments are good” and “you should comment your code”. But not all comments are created equal.

Indeed, not all comments are even good! There are some comments which make code worse, not better.

In this article, we’ll look at general principle behind commenting and how to comment your code in Python (though these principles apply to any programming language).

Without further ado, let’s get into it!

WET Comments

You may have heard of Wrote Everything Twice or WET. It is a coding concept that is conceptually opposite of another principle called DRY or Don’t Repeat Yourself.

What all of that means in the context of comments is that a good comment shouldn’t simply restate what the code is doing.

For example, consider the following comment:

import time

def time_stuff(fun):
    start_time = time.time()
    fun()
    end_time = time.time()
    return end_time - start_time

We have a function that records how long some other function took to execute in seconds. Pretty straightforward.

Imagine you asked an intern to add some comments in your project and he adds the following:

import time

def time_stuff(fun):
    # Record the start time
    start_time = time.time()
    fun()
    end_time = time.time()
    return end_time - start_time

That is a very WET comment (no offence to the intern).

The comment doesn’t add anything useful, really, and simply restates something that’s already very obvious to the reader.

Comments like these are only harmful. At some point, the function will get changed and the comment will become outdated.

Then not only wasn’t it bringing any value to start with, it would take away from the readability of the code if someone changes the function and forgets to update the common (which happens all the time).

Avoid Comments Where Code Will Do

You know what’s better than well-commented code?

Code that’s written so well it doesn’t need comments. That’s what developers should be striving towards.

You might ask “why bother”? After all, you can just drop a line or two of comments that just explains everything quickly to the reader, avoiding him the pain of thinking through what the code does.

The reason for that is code is rarely set in stone. It is a living, breathing creature that will, most likely, evolve over time.

And if that code relies on having up-to-date comments so that readers have any chance of understanding what in the f is going on, then maintaining those comments becomes just as important and burdensome as maintaining the code.

It’s far too easy to forget to update a comment after making a code change.

So how can we refactor our code such that we (often) don’t even need to comment it?

For example, consider the following code:

def calc(x):
    return x * x * 3.14

Those of you who still remember school geometry might recognise the formula here as area of cirlce. So the purpose of function calc is to, for a given radius r , calculate the area of a circle.

This function is not good at all in terms of code readability.

Your instinct might be to comment the code like:

def calc(x):
    # Calculate area of circle for radius x
    return x * x * 3.14

And that’s… better. But that code can still be improved.

Consider instead if we rewrote the code itself, such that it could serve as documentation.

After all, we can give functions and variables names so we might as well make the most of it and make them meaningful. Doing that is often far far better than any comment you could write.

Let’s rewrite the function like this instead:

import math

def calc_area_of_circle(radius):
    return radius * radius * math.pi

Ah! So much better.

Avoid How, Do Why Instead

Last but not least, a good comment shouldn’t describe how the code works. It should, instead, focus on why the code does something.

But Anton, aren’t comments means to help explain the inner workings of the code? Let me explain.

There are two problems with comments that explain how the code works.

First of all, a comment that explains how some piece of code works is bound to get outdated. The larger the chunk of code that the comment refers to, the faster it will get outdated.

Once that happens, the comment becomes actively harmful. Someone new coming in to understand the code (or even you yourself, after you haven’t looked at this code for a while) will be easily mislead about what the code is doing because of the comment.

You might argue that a good developer should double-check that the comment accurately describes the truth — but at that point, why even bother having the comment in the first place?

The second problem with comments that describe what the code does is it simply highlights the fact that the code is written in a suboptimal way.

We should strive to refactor our code, such that it is readable and self-explanatory (as much as possible).

It is true that sometimes, it’s just very very difficult to refactor code, such that it is obvious from reading the code how it works. But as a general rule of thumb, comments that describe how the code works are evil.

Commenting why the code is trying to do something gives much more context to the reader about the grander scheme of things.

This can help enormously when coming back to fix a bug or add a new feature to the code as the developer will have the context around why the code that is already there is there in the first place. What problem it is trying to solve.

In this article, we have looked at some rules for writing good comments in Python. The principles that we have described there are general enough that they extend to all or most programming languages.

By following these simple rules, your comments will be much cleaner. This will, ultimately, make your code much better.

What are some of your favourite tips for writing comments? Have you come across any other comment traps? Leave a comment (pun intended) below!

If you enjoyed this story and would like to support me as a writer, consider following me on Medium.

This will make sure you get notifications whenever I publish a new article.

You can also Sign Up For My Newsletter to get these notifications straight into your inbox.