# Runnable Specifications

This is just a draft.The content you see here is just a draft and is subject to change.

# Table of Contents

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

## Introduction

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.

**Objectives**

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

## Chapter 1: Data Lens Part 1

**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

**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

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**

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.

## Chapter 4: Composition Lens

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

## Composition Lens Supplement

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 5: Time Lens

**Model changes over time explicitly**

**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 6: 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 7: 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 8: Layers Lens

**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 9: Architecture Lens

**Build mini-models of architectural features to isolate complexity**

**Objectives**

- Learn to create models to isolate architectural complexity.