Comments should add value. And function names too. Comments should add value. And function names too. TL;DR: Don't comment on what you are doing. Name what you are doing. TL;DR: Don't comment on what you are doing. Name what you are doing. Problems Addressed 😔 Bad Names
Comments Bad Names Comments Related Code Smells 💨 https://hackernoon.com/code-smell-05-comment-abusers?embedable=true 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-xv?embedable=true https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-ii-o96s3wl4?embedable=true https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-ii-o96s3wl4?embedable=true Steps 👣 Name the function with the previous comment
Remove the Comment Name the function with the previous comment Remove the Comment Sample Code 📖 Before 🚨 <?

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

} <?

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);

} <?

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

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

} Type 📝 [x]Semi-Automatic [x]Semi-Automatic [x] 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." bijection 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 Suggested Prompt: 1. Name the function with the previous comment 2. Remove the Comment Without Proper Instructions

With Specific Instructions



ChatGPT

ChatGPT



Claude

Claude



Perplexity

Perplexity



Copilot

Copilot



You

You



Gemini

Gemini



DeepSeek

DeepSeek



Meta AI

Meta AI



Grok

Grok



Qwen

Qwen Without Proper Instructions

With Specific Instructions



ChatGPT

ChatGPT



Claude

Claude



Perplexity

Perplexity



Copilot

Copilot



You

You



Gemini

Gemini



DeepSeek

DeepSeek



Meta AI

Meta AI



Grok

Grok



Qwen

Qwen Without Proper Instructions

With Specific Instructions Without Proper Instructions Without Proper Instructions With Specific Instructions With Specific Instructions ChatGPT

ChatGPT ChatGPT ChatGPT ChatGPT ChatGPT ChatGPT ChatGPT Claude

Claude Claude Claude Claude Claude Claude Claude Perplexity

Perplexity Perplexity Perplexity Perplexity Perplexity Perplexity Perplexity Copilot

Copilot Copilot Copilot Copilot Copilot Copilot Copilot You

You You You You You You You Gemini

Gemini Gemini Gemini Gemini Gemini Gemini Gemini DeepSeek

DeepSeek DeepSeek DeepSeek DeepSeek DeepSeek DeepSeek DeepSeek Meta AI

Meta AI Meta AI Meta AI Meta AI Meta AI Meta AI Meta AI Grok

Grok Grok Grok Grok Grok Grok Grok Qwen

Qwen Qwen Qwen Qwen Qwen Qwen Qwen Tags 🏷️ Comments Comments Level 🔋 [x]Beginner [x]Beginner [x] Related Refactorings 🔄 https://hackernoon.com/improving-the-code-one-line-at-a-time?embedable=true 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 https://hackernoon.com/what-exactly-is-a-name-the-quest-part-i-fmw3udc?embedable=true Credits 🙏 Image by Jannik Texler on Pixabay Jannik Texler Pixabay This article is part of the Refactoring Series https://maximilianocontieri.com/how-to-improve-your-code-with-easy-refactorings?embedable=true https://maximilianocontieri.com/how-to-improve-your-code-with-easy-refactorings?embedable=true

Code Smell 309 - Query Parameter API Versioning

Buy My Book

Share your ideas with me!

Read My Stories

Buy Me a Coffee

Too Long; Didn't Read

Make resilience your competitive advantage

Refactoring 005 - Replace Comment With Function Name

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

Code Smell 309 - Query Parameter API Versioning

Code Smell 290 - Refused Bequest

Code Smell 293 - You Should Avoid Adding isTesting or Similar Flags

106 Stories To Learn About Clean Code

100 Pieces of Programming Advice from the Book Clean Code by Robert Martin

Code Smell 309 - Query Parameter API Versioning

Code Smell 290 - Refused Bequest

Code Smell 293 - You Should Avoid Adding isTesting or Similar Flags

106 Stories To Learn About Clean Code

100 Pieces of Programming Advice from the Book Clean Code by Robert Martin

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps