DEV Community

Cover image for Refactoring 005 - Replace Comment with Function Name
Maxi Contieri
Maxi Contieri

Posted on • Originally published at maximilianocontieri.com

9 1

Refactoring 005 - Replace Comment with Function Name

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

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;

}
Enter fullscreen mode Exit fullscreen mode

After

<?

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

function replaceBracesWithSpaces($input) {

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

}
Enter fullscreen mode Exit fullscreen mode

Type

[X] SemiAutomatic

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

Why the code is better?

Comments always lie.

It is hard to maintain comments.

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

Limitations

As always, very important design decisions are valid comments.

Tags

  • Comments

See also

What is in a name?

Credits

Image by Jannik Texler from Pixabay


This article is part of the Refactoring Series.

Sentry blog image

How I fixed 20 seconds of lag for every user in just 20 minutes.

Our AI agent was running 10-20 seconds slower than it should, impacting both our own developers and our early adopters. See how I used Sentry Profiling to fix it in record time.

Read more

Top comments (0)

Billboard image

The Next Generation Developer Platform

Coherence is the first Platform-as-a-Service you can control. Unlike "black-box" platforms that are opinionated about the infra you can deploy, Coherence is powered by CNC, the open-source IaC framework, which offers limitless customization.

Learn more

👋 Kindness is contagious

Engage with a sea of insights in this enlightening article, highly esteemed within the encouraging DEV Community. Programmers of every skill level are invited to participate and enrich our shared knowledge.

A simple "thank you" can uplift someone's spirits. Express your appreciation in the comments section!

On DEV, sharing knowledge smooths our journey and strengthens our community bonds. Found this useful? A brief thank you to the author can mean a lot.

Okay