When do we refactor code?

If you are a developer it is almost certain that you had to refactor code at some point. Refactoring is no joy, especially if it is not your code and badly written.

In the bigger picture refactoring is ever-present. Just take a look at the Drupal ecosystem. You could refactor content types, display suite fields or views.

 

In this blog post I will give you an insight in how we deal with code refactoring at Amazee Labs.

 

The three code states

I like to think that the code we write can have three states:

• stable code: code that is subject to almost no changes, and at the same time permits to easily add new functionality.
• code to be refactored: this is the code that we are working on, or it is marked with @todo and a comment regarding why and what should be refactored.
• bad code: code that should be refactored, but nobody is aware of it - at least not yet... You will only notice when the client reports a bug or a feature request that cannot be implemented without changes in that portion of code.

Managing @todos

One of the though lessons learned is that when you set a @todo, unless you reserve exclusive time for code refactoring, you will not refactor that code until it is subject of a bug. Since, our first rule regarding code refactoring is actually to try to avoid it, or to make it really early in the development stage, and not let too many @todos go into production. But in the real world, this rarely happens, there always will be @todo in the code.

 

The next thing is how you report a @todo. A bad example is:

 

// @todo: This code has to be refactored.

 

This does not give a clue what the code does now or why the code should be changed. You should always point out the reason why the code needs to be refactored.

 

 

Refactoring

Then, when the time comes to actually refactor the code, the question is: How do you refactor? It depends on the code that has to be refactored, but most of the time it involves moving code into a separate function, changing the structure of a classes tree or moving the implementation from a function oriented to an object oriented approach.

Finally, you have to check if your refactored code really works. Because you refactored the code, this does not mean that you fixed the bugs. You could even have introduced new ones. So to ensure this didn't happen, the best thing is  to have automated tests that you run on your code, which is not always a trivial task to do.

 

The five conclusions

1. If possible, try to avoid having many @todos in your code, especially in the one that goes to production.
2. Always write good documentation for what you have to refactor. It would be good to specify why the code has to be refactored, the priority and optionally why you've chosen not to refactor yet. 
3. Refactor the code as soon as possible. Ideally is in the development stage.
4. Always test the new code. If you refactor it, it does not mean that that code is correct.
5. Avoid writing code you know that you will have refactore it in the future.

If you are looking for a more general blog post on code refactoring you should take a look at SourceMaking's "Introduction to Refactoring".