The hidden downsides of tidying code

Refactoring can be more about sweeping complexity under the rug where it's harder to understand and modify.

I loved simplifying code—breaking big functions into clean, small ones felt like tidying up a messy room. It’s satisfying. But I did it without understanding the drawbacks.

For example, I would take this:

And turn it into this:

Is This A Good Idea?

• ✅ It’s a little easier to understand what processOrder is doing at a high level (though the comments largely do this already).

• ✅ You can scroll less.

• ✅ You can unit test these functions individually, if you wanted to.

• ❌ It’s a little harder to understand what processOrder is doing at a low level (requiring another function jump). In my experience, this is often what you’re doing when reading code (what are we actually validating? How are we calculating prices exactly? Etc) You’re actually reducing the signal-to-noise ratio by adding more boilerplate/indirection at the expense of the code that actually does stuff.

• ❌ You’ve created these new boundaries that describe things well now but might not in the future. What if you want to check inventory, process payments, and update inventory, as part of a transaction? What if you want to send notifications or log as part of the failure paths? The “clean” boundaries between the different parts of a function that exist right now can often get messier in the future and you’ll end up undoing a lot of what you just did.

• ❌ This extra function jump also makes it slightly more tedious to change code. You now have to plumb parameters down an additional level.

The last benefit also come with its own challenges:

• ❌ You need to write more tests and add more validation logic. Once you factor out a function, other people can call it (assuming you don’t nest it under the existing function). Once other people can call it, you can’t make the same assumptions about how it’s called. validateOrder checks if the user is active, but calculateTotal does not (which uses the user). Is that okay?

Advice for navigating the tradeoff

Personally, I’ve largely stopped “tidying” code in this manner. There are plenty of good reasons to pull code out of a larger function, but trying to make your code “clean” or “tidy” are not good reasons. Once you have to scroll to read the whole function you can start thinking about it.