Code Smell 224 - Deodorant Comments
You use nice words to excuse bad code
TL;DR: Don't excuse bad code. Write a clean one!
- Rewrite the code and delete the comment
The term comes from Martin Fowler's book "Refactoring: Improving the Design of Existing 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
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
#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
Most comments are code smells.
You can remove deodorant comments and improve the code.
- Comments should only be used to describe important design decisions.
Remove any meaningless comment you find in your code.
Code Smells are my opinion.
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.
This article is part of the CodeSmell Series.