Refactoring can feel like responsible development even when I am using it to avoid shipping.
That is what makes it dangerous.
If I spend an evening reorganizing components, I can tell myself I improved the codebase. Sometimes I did. Other times I changed names, moved files, created new abstractions and ended the night with exactly the same product a user would have seen before.
There is nothing wrong with clean code. The problem begins when “cleaner” has no finish line.
Side projects are especially vulnerable because nobody is standing beside me saying the feature must go out on Friday. I can redesign the architecture forever.
So I needed a better rule for deciding when to refactor and when to ship.
I ask whether the code is blocking a real change
My first question is simple:
What specific change is difficult because of the current code?
If I cannot answer that, I probably do not need a large refactor.
For example, imagine three components repeat the same validation logic. If I am about to add a fourth form that needs the same logic, extracting it into one reusable function makes sense.
But if the duplication is small, stable and not causing mistakes, turning it into an elaborate abstraction may not help anything yet.
I want refactoring to solve friction I can point to.
“Something about this folder feels ugly” is weaker evidence.
I separate dangerous debt from annoying debt
Not all technical debt deserves the same urgency.
Dangerous debt can cause unauthorized data access, lost user data, duplicate financial operations, broken authentication, unrecoverable migrations or crashes in a critical workflow.
I do not knowingly ship those because I am trying to move fast.
Annoying debt is different.
Maybe a component is 250 lines and I would prefer 120. Maybe two utility functions could be combined. Maybe the naming is not perfect. Maybe I know I will eventually move a query into a service layer.
Those things deserve attention, but they do not always deserve to delay the first useful version.
The user-facing path gets priority
For a side project, I identify the core journey.
What is the one thing the user came to do?
If I am building an artist-profile platform, perhaps that journey is creating an account, adding artist information, saving the profile and sharing a public link.
If those steps are unreliable, I should fix them.
If they work and the remaining refactor affects an internal settings component nobody needs for launch, it can probably wait.
This keeps my priorities connected to the product instead of my mood as a programmer.
I use a "change cost" test
Sometimes ugly code is still cheap to change.
That matters.
If a file is not elegant but I can safely modify it in ten minutes, it is not creating much practical debt yet.
If one small requirement forces me to change the same logic in seven places, the cost is already real.
So I look at three things:
Frequency: How often do I touch this code?
Blast radius: How many parts can I accidentally break?
Understanding: Can I still explain what it does without rediscovering it every time?
When all three are getting bad, refactoring has earned its place.
I do not refactor code I am about to delete
Early products change.
That means some of the code I dislike may disappear when the product direction changes.
This is one reason premature cleanup can be wasteful.
If I am still testing whether users even care about a feature, I avoid building a beautiful internal architecture around it unless safety or reliability requires it.
First I want evidence that the feature deserves to survive.
Then I can invest in making it easier to maintain.
I write down debt instead of fixing all of it immediately
A useful trick is creating a short technical-debt list.
When I notice something that should improve but does not need to block the release, I write it down.
For example:
- centralize API error messages
- split dashboard component
- remove duplicated profile query
- add tests around payment status handling
- rename confusing "data2" variable
The list removes the fear that I will forget the problem.
I can keep moving without pretending the debt does not exist.
After shipping, I can rank those items by actual impact.
I time-box cleanup before a release
Refactoring expands to fill the time I give it.
For non-critical cleanup, I sometimes define a limit.
Maybe I will spend one focused session improving the worst part of the feature. When that time ends, I run tests, check the core journey and decide whether it is safe to release.
A time box stops me from discovering a new abstraction in the middle of the old abstraction and turning one evening into a rewrite.
Tests change what I am willing to refactor
Refactoring without feedback is more stressful.
If important business logic has tests, I can change its structure with more confidence because I have something checking behavior.
If there are no tests around a fragile area, a “cleanup” can silently introduce bugs.
This does not mean every side project needs enormous test coverage. It means the risk of a refactor depends partly on how quickly I can detect a mistake.
For critical logic, I would rather add a small useful test before a large structural change.
I watch for emotional refactoring
This is the hardest type to admit.
Sometimes I refactor because the next product step is uncomfortable.
Publishing means people can judge it.
Asking users for feedback means they can say the feature is unnecessary.
Connecting a real payment flow creates responsibility.
Marketing means leaving the comfortable world of code.
Refactoring lets me stay busy without facing any of that.
When I catch myself redesigning a part that already works while avoiding a launch task, I ask:
If nobody could see the source code, would this still be the most important thing to work on today?
That question is uncomfortable because it often exposes what I am doing.
My practical shipping rule
My rule now is:
Refactor before shipping when the current structure creates a meaningful risk to security, data, reliability or the next essential change. Otherwise, record the debt, make the core journey solid and ship.
It is not mathematically precise. Product development rarely is.
But it gives me a boundary.
I am allowed to improve the code.
I am not allowed to use endless improvement as a substitute for releasing the product.
What happens after shipping
Shipping is not permission to abandon quality.
It gives me better information about where quality matters.
Once the product is being used, I can see which features are touched most, where bugs actually happen, what code changes frequently, which assumptions were wrong and which parts nobody cares about.
That makes the next refactor more intelligent.
Instead of guessing what will become a maintenance problem, I can refactor around evidence.
I still care about code I am proud to open.
I just no longer believe pride means every file must reach some imaginary final form before another person can use the product.
A side project has to become a product eventually.
At some point the best architectural decision is not another folder.
It is putting the thing in front of a real person and learning what deserves to be built next.