Refactoring 011 - How to Replace Comments With Tests

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 💨 https://hackernoon.com/code-smell-05-comment-abusers?embedable=true https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxvii https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxx https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxiii Context 💬 Comments often act as a placeholder for missing logic or verification. \ A comment explaining "what" a method does creates passive documentation. \ This documentation is detached from execution. \ As the code evolves, comments rot. \ They stop reflecting the truth and mislead the reader. \ When you convert comments into automated tests, you create active contracts. \ These contracts prove what the code actually does. Steps 👣 Take the comment of the method explaining what the function does. Rename the method with the comment description (the what). Create tests to verify the comments. Omit irrelevant implementation details. Sample Code 💻 Before 🚨 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 numbers are both positive, the result will be positive # If the numbers 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, # You can write some unit tests # that verify the behavior of the function. After 👉 def multiply(first_multiplier, second_multiplier): return first_multiplier * second_multiplier class TestMultiply(unittest.TestCase): def test_multiply_both_positive_outcome_is_positive(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) # You 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 You can rewrite the comment and compact it. \ It isn't always an algorithmic process. Safety 🛡️ This isn't a safe refactor, but it increases coverage. Why is the Code Better? ✨ Comments lie. The code doesn't. How Does it Improve the Bijection? 🗺️ Comments describe intended behavior as passive text. \ Tests prove behavior as executable contracts. \ Your code maps directly to the real-world model. Limitations ⚠️ You can't test private methods directly. \ When a comment is on a private method, test it indirectly. \ Alternatively, extract the private method into a separate object. \ You can leave comments reflecting important design decisions. Tags 🏷️ Comments Level 🔋 [X] Beginner Related Refactorings 🔄 https://hackernoon.com/refactoring-010-extract-method-object Refactor with AI 🤖 Suggested Prompt: 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. Without Proper Instructions 📵 ChatGPT Claude Perplexity Copilot You Gemini DeepSeek Meta AI Grok Qwen With Specific Instructions 👩‍🏫 ChatGPT Claude Perplexity Copilot You Gemini DeepSeek Meta AI Grok Qwen See also 📚 https://hackernoon.com/what-is-wrong-with-software-uh8j3y7k?embedable=true https://hackernoon.com/the-one-and-only-software-design-principle-1x983ylp?embedable=true Credits 🙏 Image by philm1310 from Pixabay This article is part of the Refactoring Series. https://maximilianocontieri.com/how-to-improve-your-code-with-easy-refactorings \