When it comes to software design, there’s one trap that even the smartest developers regularly fall into — trying to build skyscrapers when all they need is a cabin.
Many developers carry practices they’ve learned at work straight into their side projects — or worse, from corporate frameworks into startups — and end up freezing in a state of analysis paralysis. Let’s talk about why this happens, and how to design software that fits its context.
Software Design Is About Context, Not Rules #
The way we teach software design often strips away the single most important ingredient: context. We tell developers to follow design patterns, apply clean architecture, or enforce perfect separation of concerns — but not when or why these principles matter.
Design isn’t a moral choice between good or bad code. It’s a tool for communication between people — a way for others (or your future self) to reason about what’s going on inside a system.
The “Pattern Language” Connection #
The concept of design patterns didn’t start in programming at all. It came from the architect Christopher Alexander, who introduced the idea of pattern languages in the 1970s. His book A Pattern Language framed design as a human, adaptable process — a way to make spaces “habitable,” not rigid. Later, programmers like Kent Beck and Ward Cunningham adapted Alexander’s ideas, realizing that codebases, like buildings, should be livable — easy to modify, maintain, and evolve for their inhabitants (you and your teammates). So, instead of fixating on patterns as strict blueprints, think of them as building blocks you adapt to fit your environment.
Habitability Over Perfection #
When building a small project or early-stage startup, your goal shouldn’t be pristine architecture — it should be habitability.
Ask yourself: How long is this code going to live?
- If a startup might pivot within six months, elaborate abstractions and generalized modules won’t survive the next product direction anyway.
- Instead, focus on writing software you can live in. Code that makes sense to you.
If that means putting all your REST handlers in one file because that’s how you move fastest — do it. If separating them into modular files helps you see the system clearly — do that instead. There’s no “right” answer, only trade-offs that fit your mental model.
When You Do Need Structure #
On the flip side, enterprise environments are all about longevity and collaboration. Your code might live for years, handled by dozens of engineers. That’s where clean architecture and design principles truly shine: they create shared mental models that reduce friction and bugs as the system evolves. Following the KISS and DRY principles isn’t just about elegance — it’s about minimizing pain for the next developer who touches your code. Patterns like separation of concerns or layering HTTP, domain, and data logic are there so others (and future you) can trace how something works without pulling at five tangled threads.
How to Balance Speed and Maintainability #
The hardest context is somewhere in the middle — not quite a startup, not fully enterprise. Here’s a lightweight approach that keeps things sane without overengineering:
- Split responsibilities just enough: isolate HTTP logic, business logic, and data logic into separate functions.
- Avoid unnecessary layers like “ports and adapters” unless you’re sure the system will live long enough to justify it.
- Keep code modular but pragmatic: small, coherent chunks you can change without rewriting the world.
That’s not “clean architecture.” It’s clean enough — and that’s the sweet spot most applications actually need.
The Takeaway #
Software design isn’t about showing how much you know. It’s about building something others (or future you) can comfortably live in.
If you’re building for a startup or passion project — optimize for habitability and speed. If you’re working in a long-term corporate environment — optimize for communication and structure. Both are valid, depending on the expected lifespan of the code.
Or, as Christopher Alexander might say: don’t build skyscrapers when all you need is a cottage. Build something you can actually live in.
Because code isn’t just for machines — it’s for people too.