DEV Community: Jim McKeon

Design or Debug

Jim McKeon — Sun, 05 Jul 2026 20:18:01 +0000

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

Expressive Design: Beyond Primitives

Jim McKeon — Sun, 15 Mar 2026 02:22:21 +0000

For years I’ve struggled with how to handle very simple validation scenarios.

Most systems have identifiers with basic constraints — fixed length, allowed characters, or formatting rules. The problem usually isn’t writing the validation itself, but deciding where that validation should live and ensuring it’s applied consistently.

Consider a simple example: suppose our application models an Order, and the system requires that an order ID must be exactly 10 characters long.

For a long time I would have implemented it like this:

public class Order
{
    public string Id { get; set; } = string.Empty;
}

Nothing unusual there. Also, until fairly recently I would typically enforce validation using a separate validator:

public class OrderValidator
{
    public void Validate(Order order)
    {
        ArgumentNullException.ThrowIfNull(order);

        ArgumentException.ThrowIfNullOrWhiteSpace(order.Id);

        if (order.Id.Trim().Length != 10)
        {
            throw new ArgumentException(
                "Id must be 10 characters long",
                nameof(order.Id));
        }
    }
}

Now imagine a service responsible for creating orders:

public class OrderService
{
    private readonly OrderValidator _validator;

    public OrderService(OrderValidator validator)
    {
        _validator = validator;
    }

    public Order Create(string id)
    {
        var order = new Order
        {
            Id = id
        };

        _validator.Validate(order);

        // persist order, publish events, etc.
        return order;
    }
}

Putting aside for the moment that using exceptions for control flow isn’t ideal, this approach works, but it comes with a few undesirable side effects:

Any code responsible for creating or updating an Order needs to know that this validator exists.
The rules for a valid order ID are disconnected from the value they describe.
Invalid orders can exist until validation is explicitly invoked.

Also, what makes two orders equal in this case isn’t obvious. One possible fix is to implement equality directly on the Order entity:

public class Order : IEquatable<Order>
{
    public string Id { get; set; } = string.Empty;

    public bool Equals(Order? other)
    {
        if (ReferenceEquals(this, other)) return true;
        if (other is null) return false;

        return other.Id == Id;
    }

    public override bool Equals(object? obj)
        => obj is Order other && Equals(other);

    public override int GetHashCode()
        => Id.GetHashCode();
}

Now we can compare orders using the Equals() method, but not with the == and != operators.

Behold the Value Object

Although I haven’t read the entire book (yet), I’m a big fan of Domain-Driven Design. One of its core concepts is the Value Object. According to Eric Evans, a value object is:

“An object that represents a descriptive aspect of the domain with no conceptual identity.”

An easy way to think about value objects is that they behave like primitives such as string or int, but enforce business rules.

In our example, we could introduce an OrderId type:

public struct OrderId
{
    public OrderId(string id)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(id, nameof(id));

        if (id.Trim().Length != 10)
        {
            throw new ArgumentException(
                "Id must be 10 characters long",
                nameof(id));
        }

        Value = id.Trim();
    }

    public string Value { get; }
}

Then the Order class becomes something like this:

public class Order : IEquatable<Order>
{
    public OrderId Id { get; }

    public Order(OrderId id)
    {
        Id = id;
    }

    public bool Equals(Order? other)
    {
        if (ReferenceEquals(this, other)) return true;

        if (other is null) return false;

        return other.Id.Equals(this.Id);
    }

    public override int GetHashCode()
    {
        return Id.GetHashCode();
    }

    public override bool Equals(object? obj)
    {
        return Equals(obj as Order);
    }
}

Now there's no need for an OrderValidator, and an Order can't be instantiated with an invalid id. We can also add == and != operators so that orders compare naturally based on their Id.

Why This Works

By pushing validation into the type system, this approach yields a few practical benefits:

No more duplicated validation rules
Order identity is easy to find and understand because it's in one place
The type system now clearly communicates intent: OrderId is no longer "just a string", it's a fundamental concept like a DateTime or a class.

As more value objects are added, the application starts to resemble a self-contained, expressive framework rather than a collection of .NET primitives and utility methods.

As a corollary to #3 above, I'm a huge proponent of DDD's concept of "Ubiquitous Language". It forces everyone - project managers, subject matter experts, developers - to communicate in business-focused terms, rather than "tables" and "constraints" and "functions". There's many upsides to this approach, but the most consequential might be that it leads to fewer missed requirements.

Value objects are a small change in design, but they can have a huge impact. When rules are enforced by the type system, duplication disappears, invalid states become harder to create, and the application becomes easier to understand and navigate. Even simple value objects like OrderId can significantly improve the clarity and safety of a system.

I’ve only scratched the surface of value objects here. In future posts, I’ll explore other practical techniques for writing software that’s easier to read, easier to reason about, and easier to change. If this topic interests you, I highly recommend Implementing Domain-Driven Design by Vaughn Vernon, which explores these ideas in much greater depth.