Refactoring 011 - Replace Comments with Tests
Tags: webdev, beginners, programming, tutorial
Published: 2023-04-23 19:50:23

*Comments are dead. Tests are alive*

> TL;DR: Take your comment, compact it, and name your functions. Now test it and remove the comments.

# Problems Addressed

- Maintainability

- Readability

# Related Code Smells

{% 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-112-testing-private-methods-1gm8 %}

# Steps

1. Take the comment of the method explaining what the function does.

2. Rename the method with the comment description (the what).

3. Create tests to verify the comments. 

4. Omit irrelevant implementation details.

# Sample Code

## Before

[Gist Url]: # (https://gist.github.com/mcsee/99a20b92785fa34a4dd5c32a8623e8d4)
```python
def multiply(a, b):
    # This function multiplies two numbers and returns the result
    # if one of the numbers is zero, the result will be zero
    # if the number are both positive, the result will be positive
    # if the number are both negative, the result will be positive
    # the multiplication is done by invoking a primitive
    return a * b

# This code has a comment that explains what the function does.
# Instead of relying on this comment to understand the behavior of the code,
# we can write some unit tests that verify the behavior of the function.
```

## After

[Gist Url]: # (https://gist.github.com/mcsee/e73306c042cbc8f200fc149d78f24173)
```python
def multiply(first_multiplier, second_multiplier):
    return first_multiplier * second_multiplier
    
class TestMultiply(unittest.TestCase):
    def test_multiply_both_possitive_outcome_is_possitive(self):
        result = multiply(2, 3)
        self.assertEqual(result, 6)
    def test_multiply_both_negative_outcome_is_positive(self):
        result = multiply(-2, -4)
        self.assertEqual(result, 8)
    def test_multiply_first_is_zero_outcome_is_zero(self):
        result = multiply(0, -4)
        self.assertEqual(result, 0)
    def test_multiply_second_is_zero_outcome_is_zero(self):
        result = multiply(3, 0)
        self.assertEqual(result, 0)
    def test_multiply_both_are_zero_outcome_is_zero(self):
        result = multiply(0, 0)
        self.assertEqual(result, 0)           

# We define a test function called test_multiply,
# which calls the multiply function with different arguments 
# and verifies that the result is correct using the assertEqual method.

# 1. Take the comment of the method explaining what the function does.
# 2. Rename the method with the comment description (the what).
# 3. Create tests to verify the comments. 
# 4. Omit irrelevant implementation details
```

# Type

[X] Semi-Automatic

We can rewrite the comment and compact it, but it is not always in an algorithmic way.

# Safety

This is not a safe refactor but it increases coverage.

# Why code is better?

Comments lie. The code doesn't.

# Limitations

We cannot [test private methods](https://dev.to/mcsee/code-smell-112-testing-private-methods-1gm8).

In the unlikely event that we need to replace a comment on a private method, we should test it indirectly or extract it into [another object](https://dev.to/mcsee/refactoring-010-extract-method-object-3ff8).

We can leave comments reflecting important design decisions.

# Tags

- Comments

# Related Refactorings

{% post https://dev.to/mcsee/refactoring-010-extract-method-object-3ff8 %}

# Credits

Image by <a href="https://pixabay.com/es/users/philm1310-752382/">philm1310</a> on <a href="https://pixabay.com/">Pixabay</a>

* * * 

This article is part of the Refactoring Series.

{% post https://dev.to/mcsee/how-to-improve-your-code-with-easy-refactorings-2ij6 %}