Runnable Specifications

Table of Contents (short version)

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

• Introduction
• Chapter 1: Data Lens Part 1 — Capture information and its relationships in a data model
• Chapter 2: Data Lens Part 2 — Further explorations of encoding relationships in data
• Data Lens Supplement
• Chapter 3: Operation Lens — Operations are the heart of a domain model
• Chapter 4: Composition Lens Part 1 — Capture how operations work together
• Chapter 5: Composition Lens Part 2 — Ensure the flexibility your domain demands
• Composition Lens Supplement
• Chapter 6: Time Lens — Model changes over time explicitly
• Chapter 7: Domain Lens — Define the problem to model the right thing
• Chapter 8: Volatility Lens — Look at how things change over time
• Chapter 9: Scope Lens — Take a lateral approach to solving difficult problems
• Chapter 10: Platform Lens — Build mini-models to isolate architectural complexity
• Appendix: Annotated Worked Example

Table of Contents (long version)

• Underlined chapter titles are available to read. Just click on the title (it's a link!).
• I update page counts as I add new material.
• Status codes are as follows: Notes, Drafted, Available, Revised, Polished, Finished

Introduction — 20 pgs — DA

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 for 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 and make it worth your time and money.

Objectives

• Understand the main ideas of this book.
• Decide if this book is for you.
• Contrast this book with other software design approaches.
• Learn how to maximize your learning from this book.

Important terms

• software design
• domain
• domain modeling
• runnable specifications

Chapter 1: Data Lens Part 1 — 28 pgs — RA

Capture information and its relationships in a data model

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.

Objectives

• 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.

Chapter 2: Data Lens Part 2 — 16 pgs — DA

Further explorations of encoding relationships in data

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.

Objectives

• 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.

Data Lens Supplement — 9 pgs — DA

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 — 30 pgs — DA

Operations are the heart of a domain model

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.

Objectives

• 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.

Important terms

• function signature
• total and partial functions
• constructor, accessor, mutation, and combining functions
• definition vs implementation

Chapter 4: Composition Lens Part 1 — 37 pgs — DA

Capture how operations work together

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.

Objectives

• Learn to align the model with the relationships between operations in a domain.
• Discover how the closure property can expand the expressivity of your model.
• Understand how to encode the relationships as tests.

Important terms

• composition
• organic and synthetic approaches
• closure property
• algebraic properties
• total property
• partial property

Chapter 5: Composition Lens Part 2 — 35 pgs — DA

Ensure the flexibility your domain demands

We've worked with operations in composition and learned how to increase the expressivity of those operations, especially by leveraging the closure property. In this chapter, we will explore how to add flexibility to the operations by encoding important behaviors when they are composed together.

Objectives

• Learn to encode flexibility into your model with properties.
• Discover how to adapt generic properties to meet specific needs.
• Understand how to encode the properties as tests.
• Learn to implement the properties of your operations.

Composition Lens Supplement — 21 pgs — DA

In this supplement, we detail various algebraic properties that are commonly found in operations in real-world domains. Properties are common compositional structures that we analyze from domains. For each property, we indicate its mathematical notation and a notation in code, and an example property-based test.

You can use this supplement in two ways. Firstly, you can use it as a reference for the compositional structures to look for when analyzing a domain. And, secondly, you can use the properties within as inspiration for your own properties, since the real-world often deviates from the clean, mathematical properties algebraists appreciate. Feel free to modify these properties as needed.

Chapter 6: Time Lens — 23 pgs — DA

Model changes over time explicitly

So far in this book, our data model has encoded state at a single point in time. We modify the state by modifying the data struc-ture. However, as domain models get more sophisticated, they usually require a notion of time. For instance, in accounting, we need to know not just the current account balance, but the histo-ry of transactions that led to that balance. In this chapter, we're going to explore two ways of encoding history and use them to implement undo in our application.

Objectives

• 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 7: Domain Lens

Define the problem to model the right thing

Objectives

• 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 8: Volatility Lens

Look at how things change over time

Objectives

• 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 9: Scope Lens — N

Take a lateral approach to solving difficult problems

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.

Objectives

• 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.

Chapter 10: Platform Lens — N

Build mini-models to isolate architectural complexity

Objectives

• Learn to create models to isolate architectural complexity.

Appendix: Annotated Worked Example