DEV Community: Jim McKeon

Better Problems: The Power of Abstraction

Jim McKeon — Mon, 20 Jul 2026 22:37:13 +0000

Second in a series on practical software design.

Technical details are essential, but they're not the solution

Which is clearer?

Here's a simple user story for a lending library api:

As a library member, I want to borrow a book so that I can take it home.

And here are two code blocks that implement it. Take a few seconds to look at each. Which is easier to understand?

[HttpPost("borrow")]
public async Task<IActionResult> Borrow(int bookId, int memberId)
{
    var connectionString = _config.GetConnectionString("LibraryDb");
    using var conn = new SqlConnection(connectionString);
    await conn.OpenAsync();
    var cmd = new SqlCommand("SELECT * FROM Books WHERE Id = @id", conn);
    cmd.Parameters.AddWithValue("@id", bookId);
    var reader = await cmd.ExecuteReaderAsync();
    Book book = null;
    if (await reader.ReadAsync())
    {
        book = new Book();
        book.Id = (int)reader["Id"];
        book.Title = reader["Title"].ToString();
        book.DueDate = reader["DueDate"] as DateTime?;
        book.CheckedOutByMemberId = reader["CheckedOutByMemberId"] as int?;
    }
    reader.Close();
    if (book == null)
    {
        return NotFound();
    }
    // check if already checked out
    if (book.CheckedOutByMemberId != null && book.CheckedOutByMemberId != 0)
    {
        return BadRequest("already out");
    }
    // now get the member fines
    decimal fines = 0;
    var cmd2 = new SqlCommand("SELECT Amount FROM Fines WHERE MemberId = @m AND Paid = 0", conn);
    cmd2.Parameters.AddWithValue("@m", memberId);
    var reader2 = await cmd2.ExecuteReaderAsync();
    while (await reader2.ReadAsync())
    {
        fines = fines + (decimal)reader2["Amount"];
    }
    reader2.Close();
    if (fines > 0)
    {
        return BadRequest("has fines of " + fines.ToString());
    }
    // set due date to 2 weeks from now
    var due = DateTime.Now.AddDays(14);
    var cmd3 = new SqlCommand("UPDATE Books SET DueDate = @d, CheckedOutByMemberId = @m WHERE Id = @id", conn);
    cmd3.Parameters.AddWithValue("@d", due);
    cmd3.Parameters.AddWithValue("@m", memberId);
    cmd3.Parameters.AddWithValue("@id", bookId);
    await cmd3.ExecuteNonQueryAsync();
    // add to member checkout list
    var cmd4 = new SqlCommand("INSERT INTO MemberCheckouts (MemberId, BookId, CheckedOutOn) VALUES (@m, @b, @now)", conn);
    cmd4.Parameters.AddWithValue("@m", memberId);
    cmd4.Parameters.AddWithValue("@b", bookId);
    cmd4.Parameters.AddWithValue("@now", DateTime.Now);
    await cmd4.ExecuteNonQueryAsync();
    return Ok("borrowed");
}

[HttpPost("borrow")]
public async Task<IActionResult> Borrow(int bookId, int memberId)
{
    var book = await _books.GetById(bookId);
    if (book is null) return NotFound();

    if (book.IsCheckedOut)
        return Conflict("Book is already checked out.");

    if (await _members.HasOutstandingFines(memberId))
        return BadRequest("Outstanding fines must be cleared before borrowing.");

    book.SetDueDate(_clock.Now.AddDays(LoanPeriodDays));
    await _bookCheckoutService.CheckOutBook(memberId, book);

    return Ok();
}

If you're like me, you chose the second. Why? It's easier to parse because there's less information in it (also, it uses more intuitive variable and method names, but that's for another post). We have a limited capacity for detail, and usually only want enough to answer the question in front of us. Past that point, our capacity for analysis and critical thinking deteriorates. Less information in this case is always better.

The Case Against Detail

The second method is clearer because it abstracts the technical details that are in the first. The terms "abstracting" and "abstraction" are omnipresent in design literature: DDD, Clean Architecture, SOLID, etc., all assume you’re comfortable with it, but none of them describe how it works or how to get fluent in it. And despite being foundational, it's rarely taught explicitly. CS programs teach the language mechanisms of abstraction — abstract classes, interfaces, ADTs — but not how to apply it to requirements analysis or software design.

So we've seen how code that abstracts technical details is easier to process. But readability is the downstream benefit, the result of well designed software. The same act of substituting a symbol for a mess of detail does something more valuable earlier, when the code doesn't exist yet and you're building an understanding of the problem.

When you replace "open a connection, run this query, map these columns" with repository.GetSomething(), you're not just hiding detail from a future reader: you're deliberately hiding it from yourself, so your working memory is spent on the shape of the solution rather than the mechanics of data access. This is the real purpose of encapsulation. It gets taught as a mechanism but the reason it matters is almost never stated: holding complexity at bay so a mind can work above it.

You Already Abstract

This shift from trees to forest-first thinking can be hard for developers, but your mind already does it instinctively. Consider this: a friend just texted asking if you can meet for lunch tomorrow. Start assessing your schedule.

Most likely your thoughts didn't follow a sequence like this:

open eyes
hit snooze
stretch, yawn, rub eyes
move one leg to the edge of the bed …

You automatically grouped the morning into a single block — "get up, get ready" — then checked it against the commitments that actually matter: a mid-morning meeting, the lunch window, your afternoon. You abstracted without trying, because processing a day as a hundred discrete physical actions would be paralyzing.

In effect you answered the question by skipping the details. The minutiae of your morning routine — every step of making coffee, every minute of your commute — aren't just unnecessary, they actively get in the way. They consume the working memory you need for the actual problem: "am I free at noon?"

This is the same dynamic at work in code. The forty-line version of Borrow() forces you to hold connection strings, query parameters, and column mappings in your head before you can even see the end to end flow of the solution. At that level, the details are noise that obscure it — and worse, they let you make progress on implementation without ever arriving at a viable design. We already know this intuitively about everything except the code we write. The next section is about why.

Detail Or Die

The answer is that software development is extraordinarily complex. Just configuring an IDE, getting a debugger attached, or resolving your first merge conflict takes a real investment of time and energy. In the beginning, the details consume you because they have to — they're the price of entry.

But after you've been writing code for a while, you start to feel the cost. The code is hard to follow, fragile to change, and difficult to debug without breaking something. That frustration is a signal: the detail-first habit that got you through the learning curve is now working against you. This is where learning to abstract starts to pay off.

How to Abstract

Abstraction is thinking in terms of what happens rather than how it happens. It's holding a technical theme in your head instead of the mechanics that comprise it.

To get there, you have to short-circuit your mind's detail-focused default — the reflex to reach for the connection string, declare a variable, calculate a result before you've nailed down the high-level flow. One way to force the switch is to write down, in plain prose, what your code will do before you implement it. To demonstrate, let's construct a solution for the library API user story at the top of the post:

As a member, I want to borrow a book so I can take it home.

After giving it some thought, one possible sequence of events is:

Get the book from the app db
Verify it's not already checked out
Verify the member's fine balance is $0
Update the due date on the book
Add the book to the member's checked-out list
Save changes

That's the whole operation. Six lines, zero technical details. At this altitude you can hold the entire endpoint in your head at once, because you're thinking in responsibilities, not implementation.

And because the solution is easy to express, it's cheap to change. Look at the fine-balance check — we verify the member owes nothing, but we never checked whether the member is allowed to borrow another book at all. Most libraries cap how many items you can have out at once. It's a big miss.

To fix it we add one line:

Get the book from the app db
Verify it's not already checked out
Verify the member's fine balance is $0
Verify the member is under their borrowing limit
Update the due date on the book
Add the book to the member's checked-out list
Save changes

That edit cost a few keystrokes. Had we caught this three hundred lines into the implementation — a new query, a new branch, a new failure path threaded through code that assumed it wasn't there — it would have cost an afternoon, and more likely than not, made the code less readable and flexible. We changed our mind for free because we abstracted first.

Learning From Experience

Keeping your eye out for where abstraction might have helped is another good way to build the skill. Often, duplication is the symptom. When you see a significant code block repeated across a class or file, ask yourself: what responsibility does this represent? This applies to new code too — when you're writing something, ask yourself what existing code it resembles (even partially). If the answer is 'a lot of things,' you're looking at a missing abstraction.

As you accrue experience with this mindset, you'll start noticing shapes that repeat across systems — even systems in completely different domains. For example, a significant portion of CRUD API use cases implement some version of:

Validate input -> invoke service -> query data -> apply business rules -> construct response

These recurring shapes are the building blocks of design. I'll dig into them — what the literature calls role stereotypes — in a future post. For now, the point is this: once you start thinking in abstractions, you stop solving every problem from scratch. It's Legos vs a jigsaw puzzle.

Next Steps

The prose-first approach is a starting point — a thinking tool for breaking out of the detail-first habit and working at the right altitude. In upcoming posts I'll discuss how to use abstraction to identify responsibilities, assign them to objects and incrementally build a working design. But none of that is possible until you can see the forest first.

Better Problems: Design or Debug

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

First in a series on practical software design.

Code should document the solution to a problem, not the process of solving it.

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. It's for anyone who senses that planning the work first is the key to doing it better, but doesn't know where to begin.

In future posts I'll cover:

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.