Write Useful Code Comments

Contributed by: Maximiliano Contieri

Difficulty level: Easy

Code comments create intense debate among developers. Regardless of anyone’s opinion, you need to acknowledge that they are not parsed, compiled, or executed; sometimes they become obsolete and your compiler will ignore this fact.

As a rule of thumb, comments describing implementation are irrelevant and you should remove them.

This is an irrelevant getter comment in Python:

class Person:
    def __init__(self, name: str):
        self._name = name

    @property
    def name(self) -> str:
        # This method returns the name of the person
        return self._name

Instead, use comments to explain why you are making certain decisions and to reveal implicit behaviors.

Commenting Design Decisions

Design decisions include performance optimizations, architectural patterns, algorithmic choices, and technical analysis you made before writing the code. Commenting on these decisions within the code enables everyone to understand the context in which you made certain design choices.

For example, you can write a comment explaining the selection of a particular algorithm or data structure over another. You can leave a comment in Python or another language:

# Use a simple loop
# instead of a library function for small datasets
# to get better performance
# (see issue #20181209 for details).
for index in range(len(data)):
    # ...

You can also explain the reason behind some magic numbers:

# Using a threshold of 387 # for optimization purposes. ...