Code Smell 224 - Deodorant Comments

You use nice words to excuse bad code

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


  • Readability


  1. Rewrite the code and delete the comment


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

Sample Code


# 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


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


[X] Semi-Automatic

Most comments are code smells.

You can remove deodorant comments and improve the code.


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


  • Comments


Remove any meaningless comment you find in your code.


More Info


Code Smells are my opinion.


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.