You use nice words to excuse bad code

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

Code Smell 151 - Commented Code

Maxi Contieri ・ Jul 22 '22

#javascript #webdev #beginners #programming

Code Smell 183 - Obsolete Comments

Maxi Contieri ・ Dec 2 '22

#webdev #javascript #beginners #programming

Code Smell 146 - Getter Comments

Maxi Contieri ・ Jul 2 '22

#javascript #webdev #beginners #programming

Code Smell 05 - Comment Abusers

Maxi Contieri ・ Oct 24 '20

#codenewbie #tutorial #beginners

Refactoring 011 - Replace Comments with Tests

Maxi Contieri ・ Apr 23

#webdev #beginners #programming #tutorial

More Info

Clean Code In C#

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

Software Engineering Great Quotes

Maxi Contieri ・ Dec 28 '20

#codenewbie #programming #quotes #software

This article is part of the CodeSmell Series.

How to Find the Stinky parts of your Code

Maxi Contieri ・ May 21 '21

#codenewbie #tutorial #codequality #beginners