TL;DR: Don't excuse bad code. Write a clean one!

Problems

• Readability

Solutions

1. Rewrite the code and delete the comment

Context

The term comes from Martin Fowler's book "Refactoring: Improving the Design of Existing Code"

Sample Code

Wrong

# This is a function that adds two numbers
def s(a, b):
    # Now you are going to add a and b
    res = a + b
    # And return the result
    return res

Right

def sum(adder, anotherAdder):

    return adder + anotherAdder

If you ask ChatGPT to improve this version it will actually worsen it:

def calculate_sum(number1, number2):
    # Calculate the sum of two numbers
    result = number1 + number2
    return result

#In this improved version:
#
# The function name calculate_sum is more descriptive than sum, 
# making it clear that this function calculates the sum of two numbers.
# (Wrong) it is more imperative and mistakes the 'what' with the 'how'
#
# The parameter names number1 and number2 are more meaningful 
# than adder and anotherAdder, helping to indicate the purpose of each parameter.
# (wrong) They indicate type instead of role
#
# The comment # Calculate the sum of two numbers provides a clear 
# and concise explanation of what the function does, 
# making it easier for someone reading the code to understand its purpose.    
# (wrong) in fact, it is an example of deodorant and useless comment

Detection

[X] Semi-Automatic

Most comments are code smells.

You can remove deodorant comments and improve the code.

Exceptions

• Comments should only be used to describe important design decisions.

Tags

• Comments

Conclusion

Remove any meaningless comment you find in your code.

Relations

More Info

Disclaimer

Code Smells are my opinion.

Credits

Photo by Ana Essentiels on Unsplash

---

The reason we mention comments here is that comments often are used as a deodorant. It's surprising how often you look at thickly commented code and notice that the comments are there because the code is bad.

Martin Fowler

---

This article is part of the CodeSmell Series.