Runnable Specifications

This is just a draft.

Table of Contents

Underlined chapter titles are available to read. Just click on the title (it's a link!).



  • Understand the big ideas of this book.
  • Decide if this book is for you.
  • Learn how to maximize your learning from this book.

A friend in the book business told me the introduction is often read by someone standing in a bookstore, deciding whether to buy the book. If that's you, then welcome! I hope this introduction gives you what you need to make a buying decision. If you already own the book, it will orient and ready you for the rest of the book.

All programmers design software, so we have a sense of what it means. However, I will define it so we are on the same page. I also want you to understand the slightly cryptic title of the book. And finally, you should understand how I intended you to use the book to maximize your learning.

Chapter 1: Data Lens Part 1

Capture information and its relationships in a data model


  • Learn to analyze the structure of a domain and encode it in your language.
  • Learn to evaluate data models based on fit.
  • Understand how domain models are constructed by abstraction, encoding, and feedback.

This chapter presents a challenge to me as an author: I've got to reteach something most programmers already do intuitively without making it obvious and boring.

You probably have an intuitive sense of how to model the data of a domain. You likely do it every day. But sometimes we need to relearn the skills we rely on at a deeper level so we can build on top of the new understanding.

The data lens is all about encoding the relationships we find in our domain using features of our language with the same structure.

Chapter 2: Data Lens Part 2

Further explorations of encoding relationships in data


  • Understand the important distinction between component and peer relationships.
  • Discover when and how to reify a relationship into its own encoding.
  • Learn the various ways we can enforce the structure of our encoding.

In Chapter 1, we began our exploration of encoding the relationships among values in a domain. This chapter continues that exploration, diving deeper into the structure of more complex relationships. We get into some theory. And we end it by learning different ways to encode and enforce structure.

Data Lens Supplement

In this supplement, we detail several common relationship structures that appear in the world along with language features to encode them.

You can use this supplement in two ways. Treat this as a reference for those structures and language features. And use it as inspiration for understanding new structures and new language features you encounter.

Chapter 3: Operation Lens

Operations are the heart of a domain model


  • Understand how function signatures concisely encode the intent of a use case.
  • Discover how total functions make your domain model more robust.
  • Learn to specify requirements with functions you can't define.

Once you know how to data model, you should forget about it. Start with modeling the operations. The operations will give you so much information about how to encode your data, and since you're good at data modeling, you can do it later.

In this chapter, we're going to learn how to reason about operations without knowing how they are implemented or how the values they operate on are encoded.

Chapter 4: Composition Lens

Capture how operations work together


  • Learn to align the model with the relationships between operations in a domain.
  • Understand how to encode the relationships as tests.

The operations play a vital role in the domain model, and until now, we've considered them in isolation. But the operations also have relationships between themselves. We can extract quite a lot of information from those relationships to make better design decisions.

Chapter 5: Domain Lens

Define the problem to model the right thing


  • Discover ways to look past our biases to clearly see the problem your software is solving.
  • Learn to use that clarity to model the domain more simply and directly.

Chapter 6: Volatility Lens

Look at how things change over time


  • Learn to look at change over time to improve our design decisions
  • Learn to look at change across users to improve our design decisions

Chapter 7: Layers Lens

Take a lateral approach to solving difficult problems


  • Learn to defer decisions to a higher layer when it makes the layer cleaner.
  • Learn to wrangle tough domains by going down to a lower layer.

We have to make difficult decisions when designing. And sometimes any path we take will make a mess. But we often don't have to face the decision head on. We can take advantage of the layer structure and make a clean decision in a higher or lower layer.

Chapter 8: Time Lens

Model changes over time explicitly


  • Learn to model time explicitly in a domain.
  • Understand when modeling time is useful.
  • Discover how an explicit model of time makes implementing undo easy.

Chapter 9: Architecture Lens

Build mini-models of architectural features to isolate complexity


  • Learn to create models to isolate architectural complexity.