Clean Up Right After You Finish - Not Later

The Problem With "Later"

Technical debt is not just about bad code. It is about the cost of context-switching back to code you wrote weeks ago. When you return to clean something up later, you have to reconstruct your mental model from scratch - what was this function supposed to do, why is this variable named data2, what was the edge case this comment was about?

When you wrote it, you knew all of that instantly. But when the time passes by, so does your knowledge.

I remember that in my "Sea Battle" game, I had a file with 700+ lines of code with lots of stuff that I didn't refactor into smaller files.

Deferred cleanup also compounds. One messy file is annoying. Ten of them make you afraid to touch the codebase. Teams stop refactoring because the scope feels overwhelming, and the debt grows faster than anyone pays it down.

So, because I didn't clean it up when the file was smaller, the code compounded, and it became more difficult to clean up.

The Rule: Make It Work First

The condition for immediate cleanup is that the code works first.

Cleaning up half-working code is not good, in my understanding. If you are still figuring out the approach, you might throw the whole thing away anyway. Restructuring something before it is correct is just rearranging the problem.

First, you make it work, then you make it right. That's it.

Once you have finished a unit of work, stop before moving on and spend 5-10 or more minutes on it. There, you have to have some discipline, as sometimes you really want to jump straight into the next feature. But be patient and make your existing code better. This way, you avoid a mess down the road.

What Cleanup Actually Means

Cleanup at this stage is not a big refactor. It is small, targeted, and fast:

• Remove debug console.log calls
• Delete commented-out code
• Rename variables that got placeholder names like temp or data
• Extract a function if something grew too long during implementation
• Remove dead branches that never fire

This takes minutes, not hours. The goal is to leave the code in the state you would want to find it in tomorrow.

What to Defer

You do not need to clean up everything in this cleanup pass.

• Structural refactoring - if the feature itself might change or expand, wait. Abstraction is expensive to undo.
• Performance optimization - do it when you have evidence it is a problem, not every time.
• Generalization - the rule of three: do not abstract a pattern until you have seen it at least twice in concrete form.

You do immediate cleanup to have clarity, not architecture. Architecture decisions need more information than a single feature provides.

The Practical Benefit

When you do small, immediate cleanup, it has a side effect that is easy to miss: your diffs get cleaner.

A pull request that contains a feature plus its immediate cleanup is easier to review than a feature PR followed by a separate "misc cleanup" PR two weeks later. Reviewers see what you meant to write, not the mess you made while figuring it out.

You also build a habit. Cleanup becomes part of finishing, not a separate chore you'll never get to.

Conclusion

There is an old principle in software: leave the code cleaner than you found it. Cleaning up as you go is how that principle actually gets applied. Not in a dedicated sprint. Not in a mythical "refactoring week". Right after each feature, one small pass, while you still remember what everything means.

Found this helpful? Please share it with someone who also might find it helpful. Would you like more posts from me? Subscribe to the newsletter. Got questions? Send an email to commitnobug@outlook.com.