Refactoring 005 - Replace Comment with Function Name

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;

}

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.