Imagine this situation (one I’ve been in too many times): you have been working on a piece of code and have created a complicated/intricate function. You look over your work and realize it is an ugly mess; the function is over 100 lines long and a tangled jumble of logic. However, it works and is tested; you are tired of working on this function since you have already spent so much time on it. At this point you consider two options: refactor the code or leave a comment indicating that this code should be refactored.

// This code needs refactoring

// Refactor this later
void SomeoneRefactorMeSinceMyCreatorHatesMe()
{
 // Save me
}

It is tempting to leave a comment to refactor and move on, but this decision is supported by some problematic assumptions.

1. I will fix it later

You won’t.

Once a developer puts the comment “refactor this later” on a function and checks it in he has already washed his hands of the function. I often see comments like this. Sometimes they stay in the code base for years without anyone ever addressing them. Often the original developer has long left the project but these comments remain. When asked about them, the author usually responds, “OH YEA! I forgot about that…”.

Not surprising; that comment expresses the developer’s disdain for the job that needs to be done. It follows that this developer will “forget” to come back and fix it. Is this cognitive dissonance rearing its ugly head? The developer knows he doesn’t want to work on it and thus conveniently forgets to return to it.

2. Someone else will fix it

They won’t.

If the author is unwilling to clean up his mess it seems unlikely that anyone else will jump at the opportunity. Plus, code that needs refactoring will be much harder for another developer to comprehend. (Even the author’s understanding of the code will wane the longer he waits to fix it.)

Leaving a comment to refactor is also disrespectful to other developers on the project. Instead of taking my garbage to the curb I carry it into work and dump it on another developer’s desk. If you realize your code is bad you should respect other developers enough to not force them to deal with it.

3. My time is better spent increasing functionality

It isn’t.

“Because this function works and there are other features to complete, refactoring now is a waste of time.” This thought devalues code quality in favor of functionality, which may seem like a good idea now but in the long term will hurt the project. When a function like this is left in the code it causes the entire code base to slowly creep towards an unmaintainable state. This is a concept called software rot. When the next developer needs to work with this function it will take him longer to understand and update, resulting in future features which take longer to complete. Pieces of code exist that developers *dread*. Work is delayed because developers avoid the messy code.

Refactor Early, Refactor Often

Quality of code is vital to a healthy software project. It may be scary to tell your project manager you will not ship functionality because of refactoring needs, but a good manager will appreciate that doing so now is better in the long run, and relying on a future fix is detrimental to the project. While it may feel more productive to move away from one piece of laborious code, in the end take pride in clean and easily understood code. Your team will thank you.