Work Through Examples

One of the biggest challenges in building software is specifying what needs to be built. A blueprint captures all of the valuable information we need in order to build a building and details such as the tensile strength of the material and how to build a foundation are available through other sources. Blueprints have no ambiguity. They are clear specifications.

But software is much more difficult to specify than the structure of a building. Programming languages are fundamentally different than spoken languages and there's rarely any one-to-one mapping between them. We speak in generalizations much of the time, but computers are very, very specific all of the time. This is a challenge in the way we think and communicate.

Communication by its very nature is a serial activity. When we describe processes we do so sequentially. This often implies a procedural approach and can lead to overly concrete requirements when we talk about software.

Good programmers know that there are other approaches to software design than procedural and that modeling software with objects can improve maintainability. But object-oriented programming adds additional levels of abstraction and complexity in order to give that additional flexibility.

All of this can be very abstract, and so I find it incredibly helpful to work through examples.

Rather than spending time laboring over requirements, I now think of a couple of examples I can work through with the product owner and developers so that we get on the same page for exactly what a feature should be. I often like to start with a simple example — the simplest that I can think of. Once I get a sense of how I can work through that example, I have a much better sense of what I need to code.

For example, instead of saying, bids from logged-in users higher than the current bid become the high bid on active auctions, we can say, given an active auction and a logged in user, when the bidder bids over the current bid then they become the high bidder and their bid price becomes the current price.

Examples concretize the abstract requirements and shift the conversation from "what if" to "what is." This is really important because we can spend a lot of time in "what-iffing." And that time is usually wasted — the future is anyone's guess. Instead, if we focus on solving a real problem that is in front of us then we can take the idea out of the hypothetical and bring it into the immediate, which is where our brains are used to living.

We naturally think in examples. When I give you a generalization, such as all people have feelings, you visualized a specific person, consciously or subconsciously, in order to make sense of my words. Since we always think in examples, when we specify behaviors with examples, it's more straightforward to understand and there's less room for ambiguity.

I find examples especially valuable for helping to ferret out some of the details that would otherwise need to be answered during development. In my planning sessions, we often spend our time working through examples rather than making estimates.

Good examples should specify generalizations and not be too specific. They are not meant to capture every little detail or edge case. They are simply meant to call out the main distinctions in a system and keep us focused on what does and not how the feature does it. I find that working through examples helps developers and product owners quickly get on the same page and understand a feature in enough detail to start building it.