I originally posted this post on my blog a long time ago in a galaxy far, far away.

Blindly following coding principles is a bad idea.

"Leave the basecamp cleaner," "Make the change easy then make the easy change"...

Often, we follow those two principles and start huge refactoring sessions with good intentions but without considering the potential consequences.

Let me share two stories of refactoring sessions that led to unintended consequences and the lesson behind them.

Changing Entities and Value Objects

At a past job, a team member decided to refactor the entire solution before working on his task.

He changed every Domain Entity, Value Object, and database table. What he found wasn't "scalable" in his experience.

The project was still in its early stage and the rest of the team was waiting for his task.

One week later, we were still discussing about names, folder structure, and the need for that refactoring in the first place.

We all were blocked waiting for him to finish the mess he had created.

Changing Class and Table Names

At another job, our team's architect decided to work over the weekend.

And the next thing we knew next Monday morning was that almost all class and table names had been changed. The architect decided to rename everything. He simply didn't like the initial naming conventions. Arrrggg!

We found an email in our inboxes listing the things he had broken along the way.

We spent weeks migrating user data from the old database schema to the new one.

Massive Unrequested Refactorings

These are two examples of huge refactoring sessions that went sideways. Nobody asked those guys to change anything in the first place.

Even there was no need or business case for that in the first place.

I have a term for these refactoring sessions: massive unrequested refactorings — huge refactoring sessions that don't move the needle of the project and end up with unintended consequences.

The Need for Refactoring

I'm not saying we shouldn't refactor our code.

I believe in the "leave the basecamp cleaner than the way you found it" mantra.

But, before embarking on a massive refactoring, let's ask ourselves if it's truly necessary and if the team can afford it, not only in terms of money but also time and dependencies.

Often, we get too focused on naming variables, functions, and classes to see the bigger picture and the overall project in perspective.

"Perfect is the enemy of good."

And if there isn't a viable alternative, let's split that massive refactoring into separate, focused, and short Pull Requests that can be reviewed in a single review session without much back and forth.

The best refactorings are the small ones that slowly and incrementally improve the health of the overall project. One step at a time. Not the massive unrequested ones.

Parting Thoughts

Voilà! That's my take on massive unrequested refactorings. Have you ever done one too? What impact did it have? Did it turn out well? Remember, all code we write should move the project closer to its finish line. Often, massive unrequested refactorings don't do that.

In my two stories, those refactoring sessions ended up blocking people and creating more work.

These refactorings remind me of the analogy that coding is like living in a house. A massive unrequested refactoring would be like a full home renovation while staying there!

Join my free 7-day email course where I distill 10+ years of career lessons into 7 short emails. Save years and thousands of dollars' worth of career mistakes while you refactor your software engineering career.

Happy coding!