Design or Debug

A Familiar Frustration

It’s 4 p.m. on a Friday, and I’ve spent the day working on a new high-priority enhancement. We discussed the requirements over email, chat, video calls, and several standups, and each time I walked away from these interactions reasonably confident that I understood the ask.

Now I’m deep into the implementation when the realization hits:

Wait. I didn’t consider that.

Maybe I made an assumption that was never actually supported. Maybe I just remembered something that was said last week. Maybe two requirements contradict each other. Whatever the cause, the result is the same: the solution no longer holds, a large portion of the code needs to be rewritten, and I’m already thinking about how I’m going to explain the delay.

Without a doubt, this experience has been the single largest cause of frustration and stress over the course of my career. And based on my conversations with other developers, it's a very common one. The cause isn't a lack of aptitude, focus, or discipline. It's that I started building without a considered plan. The mistake, the missed dependency, the contradiction — they were always going to surface. The only question was when. And by discovering them at the end of a Friday, with the code already written, I've maximized their destructiveness.

Things changed when I started hunting these problems down before writing any code. The contradiction or miss is still there, but caught in design, it never becomes a mistake, just a decision to make.

The Time You Don't Think You Have

I've worked in some extremely demanding environments. The work you're handed and the deadline attached to it are, more often than not, in open conflict — the ask underspecified, the timeline set before anyone understood the ask. In cultures like this, design reads as stalling. Time spent thinking is time stolen from actual work. Questions are unwelcome, because every real one exposes complexity nobody wanted to admit was there.

Opening VS Code and typing feels like progress. Stepping back to think feels like stalling — worse, it feels like the thing you do when you're not sure what you're doing.

But here's what those environments taught me: uncertainty and risk are unavoidable. We just get good at hiding them — from the people we report to, and from ourselves. It's a shell game. The people above you don't want to hear why something is hard, or impossible. You don't want to fail. So the unresolved questions get pushed to the back burner, until they boil over — at 4 p.m. on a Friday, in code you've already written, on the deadline you were protecting by not asking.

Design and debugging are often the same problem-solving work performed at different times. That’s the thing about skipping design: the task doesn’t disappear. It moves, and it grows.

A Wicked Problem

By its nature, software development exceeds our ability to hold every rule, dependency, interaction, and unresolved question in our heads at once. It's been likened to a wicked problem: our understanding of the solution changes as we attempt to solve it, and the solution itself exposes new constraints, contradictions, and unanswered questions.

Over the course of my career, I’ve learned a few things to be consistently true:

• Nothing is as simple as it seems, no matter how confidently the project manager or product owner insists otherwise.
• Mistakes are inevitable. I will make unsupported assumptions, misunderstand requirements, reverse operands, and misspell variables. The people I depend on for crucial information will make mistakes too.
• A simple word, phrase, or concept can mean different things to different people (I recently sat through a standup discussion of what "send" vs "push" mean).
• Customers will change their minds. More often than not, people do not fully know what they want until they see an example of what they don't.

Software is therefore not simply constructed from a complete and stable set of requirements. The software itself becomes a proof of concept that users evaluate, reject, and refine.

Once we accept this, design becomes more than deciding how to build a feature. It also becomes the process of identifying what might prevent the feature from working: conflicting requirements, hidden dependencies, unsupported assumptions, misunderstood language, and missing information.

The Work of Design

I've made the case that design catches problems early. But that's only one of its benefits. Even when nothing goes wrong — no contradiction, no missed dependency — designing first produces better software.

That's because design is as much an analytical process as a diagnostic one. Working out which behaviors are needed and where they belong breaks one overwhelming problem into smaller, simpler ones. The design is where I think; the code is where I record what I decided. Skip the thinking and the code becomes the place I think — which is why it comes out tangled, reworked in place, shaped by whatever I understood the moment I typed each line rather than by the whole.

It's also constructive. Intentionally designed code is easier to understand because it maps to how the problem actually decomposes. It's easier to fix, because a change has an obvious place to go. And it's easier to extend, because its structure is modeled on the real process it serves, rather than assembled from whatever shape the code happened to take as I wrote it. Let the structure emerge by accident and you get code that works only for the context it was written in, and resists attempts to change it later.

Neither benefit here depends on catching defects. They're what you get from thinking about shape before shape is expensive to change. Problem-prevention is the same act seen from the other side — the roadblocks surface while you're deciding how the pieces fit, before any of it reaches code.

Problems Are the Product

Unanticipated problems in software are inevitable. But they don't get in the way of the work, they are the work: elegant design is just a hard problem handled well. Strip out the contradictions and the edge cases and there's nothing left to build, nothing to solve, nothing satisfying about having solved it. Finding those problems early and building them in — as features, not fixes — is the craft. The rest of this series is about finding and shaping those problems before they become disruptive:

• The Power of Abstraction: the implied skill needed to put DDD, Clean Architecture, and SOLID into practice
• Behaviors and Interactions: modeling responsibilities, interfaces, and the collaborations between them
• Just Enough Design: a lightweight, iterative process for turning uncertainty into working software