Comments should add value. And function names too.

TL;DR: Don't comment on what you are doing. Name what you are doing.

Problems Addressed 😔

• Bad Names
• Comments

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-xv?embedable=true

https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-ii-o96s3wl4?embedable=true

Steps 👣

1. Name the function with the previous comment
2. Remove the Comment

Sample Code 📖

Before 🚨

<?

function repl($str) {
  // Replaces with spaces the braces 
 
  $str = str_replace(array("\{","\}")," ",$str);
  return $str;

}

After 👉

<?

// 1. Name the function with the previous comment
// 2. Remove the Comment

function replaceBracesWithSpaces($input) {
  
  return str_replace(array("\{","\}")," ", $input);

}

Type 📝

• [x]Semi-Automatic

Some IDEs have this refactoring although naming is not fully automatic.

Safety 🛡️

This is a safe refactoring.

Why is the Code Better? ✨

Comments always lie.

It is hard to maintain comments.

On the contrary, Functions are alive and self-explanatory.

How Does it Improve the Bijection? 🗺️

A comment only describes the code in natural language.

If you change the code, the comment and the behavior can drift apart, breaking the mapping between intention and execution.

When you replace a comment with a well-chosen function name, you create a direct bijection between "what the code does" and "how you call it."

The name becomes the single source of truth.

This keeps the mental model aligned with the actual implementation, so both the reader and the compiler operate on the same unambiguous contract.

Limitations ⚠️

As always, very important design decisions are valid comments.

Refactor with AI 🤖

Suggested Prompt: 1. Name the function with the previous comment 2. Remove the Comment

Tags 🏷️

• Comments

Level 🔋

• [x]Beginner

Related Refactorings 🔄

https://hackernoon.com/improving-the-code-one-line-at-a-time?embedable=true

See also 📚

https://hackernoon.com/what-exactly-is-a-name-the-quest-part-i-fmw3udc?embedable=true

Credits 🙏

Image by Jannik Texler on Pixabay

This article is part of the Refactoring Series

https://maximilianocontieri.com/how-to-improve-your-code-with-easy-refactorings?embedable=true