DEV Community

Cover image for Twelve Files for Twenty Lines: When Clean Code Becomes the Problem
Ibrahima D.
Ibrahima D.

Posted on

Twelve Files for Twenty Lines: When Clean Code Becomes the Problem

I've seen code that ticked every box. Small functions. One responsibility per class. Interfaces everywhere. Not a single line you could call ugly.

And nobody could change it.

I remember one ticket: add an optional phone number to a form. We estimated half a day. It took three, and twelve files. Most of that time didn't go into changing the code. It went into finding where things happened.

To understand what happened when a user clicked "Save", you had to follow six jumps: a handler that called a service that called a factory that built a strategy that delegated to a mapper that finally touched the data. Twenty lines of real logic, spread thin over an architecture built for a future that never came.

Everyone who had written it was proud of it. Everyone who had to maintain it was afraid of it. Not because any piece was hard. Because you had to hold all of them in your head at once.

We don't talk about this enough. We have a hundred articles on how to clean up messy code. We have very few on the opposite failure, because the opposite failure looks like virtue.

What it looks like

Here's an illustration. Not real code from a real project, but if you've been around, you've met its cousins.

The task: apply a discount to an order if the customer is a member.

// DiscountStrategy.ts
export interface DiscountStrategy {
  apply(amount: number): number
}

// MemberDiscountStrategy.ts
export class MemberDiscountStrategy implements DiscountStrategy {
  apply(amount: number) { return amount * 0.9 }
}

// NoDiscountStrategy.ts
export class NoDiscountStrategy implements DiscountStrategy {
  apply(amount: number) { return amount }
}

// DiscountStrategyFactory.ts
export class DiscountStrategyFactory {
  create(customer: Customer): DiscountStrategy {
    return customer.isMember
      ? new MemberDiscountStrategy()
      : new NoDiscountStrategy()
  }
}

// OrderPricingService.ts
export class OrderPricingService {
  constructor(private factory: DiscountStrategyFactory) {}
  price(order: Order) {
    return this.factory.create(order.customer).apply(order.amount)
  }
}
Enter fullscreen mode Exit fullscreen mode

Five files. Every one of them is "clean". Each class has one job, each name is honest, each piece is testable alone.

And here's the same thing:

function priceOf(order: Order) {
  const discount = order.customer.isMember ? 0.9 : 1
  return order.amount * discount
}
Enter fullscreen mode Exit fullscreen mode

Three lines. You read it once and you know everything.

"But what if we add more discount types?" Then you'll change it, on the day you add them, knowing what they actually look like. Which is almost never what you imagined a year before.

The cost nobody measures

Count the files and you still miss the real price. The real price is paid in your head.

To read the three-line version, you hold one thing in mind. To read the five-file version, you hold five: the interface, the two strategies, the factory, the service, and how they connect. None of them is hard. But you have to keep all of them loaded at once to answer one question: what does a member pay?

That's cognitive load, and to me it's the main problem with this kind of code. Working memory is small. Every jump spends some of it on the structure instead of on the problem. By the sixth jump, you've forgotten why you opened the first file.

No linter reports it. No coverage tool measures it. It shows up elsewhere: in onboarding that takes months, in estimates that double, in the bug nobody wants to pick up.

"AI will handle it"

I hear this more and more. The model writes the twelve files in seconds, and it can walk you through them too. So who cares about the indirection?

I do. Typing was never the bottleneck. Understanding is. AI makes structure cheap to produce, which makes it cheap to produce more structure than anyone can hold in their head.

This part is personal opinion: the day you lose your grip on your own code, you lose the core of the job. My test is simple. When someone tells me "it's broken here", I want to know right away which file to open, where to put the breakpoint, what to test. If I need a tool to explain my own codebase before I can start debugging, it isn't really my code anymore.

Why we do it

I've been that developer. I think most of us have, right after we discovered design patterns.

The first reason is that rules are easier than judgment. "Functions should be short" can be checked by a linter. "This code should be easy to change" can't. So we optimize what we can measure, and a codebase can score perfectly on every rule and still be miserable to work in.

The second is fear. An abstraction "just in case" feels like insurance. It isn't. Insurance pays when the accident happens. A speculative abstraction costs you every day, and when the real requirement arrives, it's usually the wrong shape, and now you have to undo it first.

The third is harder to admit. Elegant code is satisfying to write. That's not a crime. But the reader doesn't get the pleasure. They only get the indirection.

How I tell the difference now

Clean code isn't the code that ticks the most rules. It's the code the next developer understands quickly and changes without fear.

So I've replaced the rules with four questions:

  1. How many files do I open to change one behavior? If the answer is more than two or three for a small change, the structure is working against me.
  2. Can I point to the second use? An interface with one implementation is a question, not an answer. I want to see the second caller before I build for it.
  3. Could a newcomer follow it in one sitting? If understanding a click takes six jumps, the code isn't clean. It's hidden.
  4. When it breaks, do I know which file to open? If a bug report doesn't point me somewhere within seconds, I've lost the map of my own code.

And a habit that follows from them: sometimes I defend the ugly function. Thirty lines, top to bottom, a few ifs, readable at a glance. In review, someone suggests splitting it into five. I ask what we gain, and who it's for.

Sometimes the answer is good, and we split it. Often there isn't one.

What finally got that codebase simplified wasn't a refactoring plan. A new developer joined, spent two weeks on a one-line fix, and asked in a retro why saving a form needed six classes. Nobody in the room had a good answer. So we started inlining, one flow at a time, each time we had to touch one.

What I'm not saying

I'm not saying patterns are bad, or that a 400-line function is fine. I wrote a whole article about the principles I code by, and I stand by them. KISS and YAGNI are on that list for a reason: they're the two principles that protect you from the others.

The goal was never beauty. It's maintainability. Most of the time they agree. When they don't, I know which one I'm paid for.

Have you ever worked in code that was too clean to maintain? What did it look like, and what finally got it simplified? And does AI change the answer for you?


I write about front-end architecture and modernizing legacy code. More on my site. Let's talk on LinkedIn.

Top comments (0)