Refactoring 005 - Replace Comment with Function Name

Refactoring 005 - Replace Comment with Function Name

Comments should add value. And function names too.

Maxi Contieri
·Jun 7, 2022·

1 min read

Subscribe to my newsletter and never miss my upcoming articles

Play this article

Table of contents

  • Problems Addressed
  • Related Code Smells
  • Steps
  • Sample Code
  • Type
  • Why the code is better?
  • Limitations
  • Tags
  • See also
  • Credits

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;

}

After

<?

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

function replaceBracesWithSpaces($input) {

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

}

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

Photo by Jannik Texler on Pixabay


This article is part of the Refactoring Series.

 
Share this

Impressum

Technical Opinions are my own. I don't have the revealed truth.

Software Design is a creative activity. These are hints and not rigid rules.

I write on BackEnd Business Systems and OOP Design. My advice/experience might not suit other systems.

You can write me at info(at)maximilianocontieri.com