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

Code Smell 05 - Comment Abusers

Maxi Contieri ・ Oct 24 '20

#codenewbie #tutorial #beginners

Code Smell 75 - Comments Inside a Method

Maxi Contieri ・ Jun 5 '21

#codenewbie #tutorial #oop #programming

Code Smell 06 - Too Clever Programmer

Maxi Contieri ・ Oct 25 '20

#codenewbie #tutorial #beginners

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

Image by Jannik Texler from Pixabay

---

This article is part of the Refactoring Series.