Organizing code in a complex project is a significant challenge—huge, even. It’s not the biggest problem in a business, but it ranks up there with managing people.

I’ve seen this in larger teams and shrugged it off as “just the way things are.” But I truly felt it when I started building my own complex projects.

Initially, I’d tackle the biggest technical hurdles first, get them working, and gain an understanding of how things fit together. The result? A mess of spaghetti code. With my understanding and working (but messy) code in hand, I’d take a “day off” from technical challenges to refactor—creating libraries, defining interfaces, and organizing everything into simple, clean functions.

This gave me a solid building block. Then, I’d move to the next technical hurdle, solve it, deepen my understanding, and refactor again into clean components.

Eventually, with enough clean building blocks, I’d start thinking about architecture—how to make them work together effectively. For example, in a game project, I had objects created and destroyed in large batches, causing micro-interruptions in the framerate. I solved this with object pools—reusing objects because I understood their lifecycle and knew I’d need them again.

Screens, layers, and other elements followed. Treating them as afterthoughts led to more spaghetti code. So, I’d understand them fully and refactor them into clean components.

Why? Because spaghetti code is a liability. It means the understanding lives in your head, not the code. Six months later, that understanding fades, leaving you with a mess to decipher anew.

Well-named functions, clear interfaces, and concise methods (doing exactly what they promise, no more) move that understanding from your head into the code. Add well-written comments explaining why you made certain choices, and you’ve reduced that liability.

This approach worked for me as a solo developer.

Then, I teamed up with a friend on a Java Spring Boot project. Rediscovering Java—a modern language now—and leveraging Spring Boot’s capabilities was exciting. It felt like I was mostly configuring it, and it handled the rest.

With many technical hurdles already solved by existing libraries, I moved fast, building working demos tucked neatly into classes. Spring Boot’s constraints guided me toward cleaner code—or so I thought.

At some point, my friend sat me down and said, “This is great demo code, but it’s not sustainable. We need to get your business domain understanding out of your head and into the code.”

He pointed out I was creating spaghetti code disguised as clean code. I was so focused on Spring Boot internals—repositories, entities, services, controllers, configuration, security—that I’d lost sight of my own problem domain. Questions arose: Why is business logic in this controller? Why does this service need access to these repositories? Why enforce this constraint in the frontend?

It became clear my “business logic” was scattered everywhere. Adding a feature or making a change required touching multiple places, coordinating changes, and leaving comments like, “If you change this, update that too.”

He introduced me to clean architecture: Keep repository logic in implementation details—not core application concerns. Use plain old Java objects (POJOs) to reflect the business logic, load them from repositories, perform operations, and save the results back.

I was sold. We overhauled the codebase. Afterward, I could modify business logic without worrying about breaking unrelated parts, confidently add services, and incorporate tables I’d previously avoided.

Development accelerated. Liability decreased.

Here’s the lesson: Technical debt—or liability—has two components:

1. Understanding trapped in someone’s head (sometimes called “arcane knowledge”). Writing documentation might seem like a fix, but it’s naive—it creates additional liability by requiring you to maintain both code and docs.
2. Spaghetti code—working code where the “why” isn’t clear, and the understanding lives elsewhere (in docs or someone’s head).

Frequent refactoring should address both.

If you’ve worked on a large project, you know what I mean. And there’s never enough time to do it.

As an avid LLM user, I’ll add this: AI doesn’t solve understanding. It can tidy code into neat pieces, but it often produces disguised spaghetti code, especially in frameworks like Spring Boot. It can write clean code but not clean architecture—unless you guide it explicitly.

Once you deeply understand your problem, you can prompt an LLM to implement it. The bonus? You’ll document your thinking in the process, which you can keep for later.

More on this later.