Code Smell 224 - Deodorant Comments
Tags: webdev, beginners, programming, python
Published: 2023-09-10 23:55:49

*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

[Gist Url]: # (https://gist.github.com/mcsee/fd3612b1beeb9cde934bec4eca92bf16)
```python
# 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

[Gist Url]: # (https://gist.github.com/mcsee/57f6e1f31f3cd599deafc21236ae71ce)
```python
def sum(adder, anotherAdder):
    
    return adder + anotherAdder
```

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

[Gist Url]: # (https://gist.github.com/mcsee/57bce159d43ab49377e9de2de1e6706d)
```python
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

{% post https://dev.to/mcsee/code-smell-151-commented-code-5d8l %}

{% post https://dev.to/mcsee/code-smell-183-obsolete-comments-3mmo %}

{% post https://dev.to/mcsee/code-smell-146-getter-comments-3pjn %}

{% post https://dev.to/mcsee/code-smell-05-comment-abusers-2ba5 %}

{% post https://dev.to/mcsee/-refactoring-011-replace-comments-with-tests-27j1 %}

# More Info

[Clean Code In C#](https://learning.oreilly.com/library/view/clean-code-in/9781838982973)

# Disclaimer

Code Smells are my [opinion](https://dev.to/mcsee/i-wrote-more-than-90-articles-on-2021-here-is-what-i-learned-1n3a).

# Credits

Photo by [Ana Essentiels](https://unsplash.com/@ana_essentiels) on [Unsplash](https://unsplash.com/photos/Eh6iapfqDzA)
    
* * *

> 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_
 
{% post https://dev.to/mcsee/software-engineering-great-quotes-26ci %}

* * *

This article is part of the CodeSmell Series.

{% post https://dev.to/mcsee/how-to-find-the-stinky-parts-of-your-code-1dbc %}