That’s really all you need to know to understand the hype around AI. AI is fun to play with — addictively so. It’s essentially a slot machine. You put some money in, pull the lever, and some code that might be useful comes out. It probably won’t actually be what you wanted. It will almost certainly have flaws. But it’s conceivable, and indeed mathematically possible, that it might be perfect. That tantalizing possibility keeps us pulling the lever again and again.

There’s some geek-specific psychology going on too. LLMs are tools that seem very powerful and yet, at the same time, are observably imperfect. That combination is catnip for computer geeks of all stripes. Our absolute favorite thing to do is take an imperfect system, tinker with it or build a wrapper around it, and make it work better. And LLMs give us no end of opportunities to tinker.

The tinkering instinct is, I think, what Richard Gabriel was talking about when he wrote “The Rise of Worse is Better.” The core idea of the worse-is-better philosophy is that if you want to make successful software, you shouldn’t try to release a perfect product. Instead, release something simple and easy to tinker with, that solves at least part of the problem. If it’s useful, a whole community of geeks will spring up around it, eager to sand down its rough edges. The result will be software that fits their needs better than anything you could have designed upfront.

“Worse is better” says, in essence, this: approaching software design as an engineering problem is very expensive. But if you instead approach it as a psychological problem — asking not “what should we build” but “how do we get programmers to work on this” — you can create a lot of value at little cost to yourself. We could summarize the traditional worse-is-better business strategy as:

1. Release imperfect software

2. Get programmers to work on it for cheap

3. Sell the software

4. Profit!

Here’s the secret that every successful software company is based on: You can domesticate programmers the way beekeepers tame bees. You can’t exactly communicate with them, but you can get them to swarm in one place and when they’re not looking, you can carry off the honey.

—Orson Scott Card

AI companies like Anthropic have taken the same psychological trick and applied it in a slightly different and arguably simpler way:

1. Release imperfect software

2. Charge money for the privilege of trying to improve it

3. Profit!1

In this new regime, the “improved” software is never sold, because it doesn’t have to be. What the AI companies realized is that there is so much surplus in the system that the worse-is-better process doesn’t even have to produce valuable software; the geeks will show up regardless. Geeks tinker just because they like to tinker. Software development is entertainment, and when something is entertainment you can simply charge money for it directly.

You can see the effects of this strategy playing out at almost any software company. For instance, my coworkers have written dozens of “skills” for Claude Code that sit on the shelf unused. Developing useful software is not the point of all this. The process is the product. The point is to have fun.

A couple months ago, I spent several weeks building my own “agentic” LLM harness. Perhaps I’ll write about it in greater detail at some point; for now, suffice it to say that the results I get from it are better than vanilla Claude Code but still not good enough for production, which I guess should tell you something about how good I think Claude Code is.

Of course I bootstrapped the whole project using AI. After about 6 weeks of committing 90% LLM-written code, I had to go over the codebase with a fine-toothed comb, fixing all the weird issues the LLM left behind.

Just last week, I tried to use my custom harness to make a large (~1000 line) change to an open-source codebase. On the face of it, it should have been straightforward: I changed one of the core data types and told the AI to fix up all the code to match the new types. However, in spite of the apparent simplicity of the task, the AI couldn’t hack it. The resulting pull request had so many issues that I decided to redo it by hand. You can take a look at the AI-generated PR here, and at my manual rewrite here. The FIXME comments in the AI-generated pull request are written by me; they are how I communicate my desired changes to the LLM. You can see where I went a little crazy reviewing the AI’s crappy code and just started screaming at it.

All that’s to say, the “productivity” benefits from AI remain elusive. However, I can conclusively and authoritatively state that it is a lot of fun! Building my own LLM harness was the most fun I’ve had writing code in years. I actually stayed up late one night working on it, which for me is unheard of. Even using it is fun, in spite of its flaws. When it produces something useful, I get a big dopamine hit. I made the machine do a thing. When its code is crap, I get to feel superior as I fix all its weird goof-ups. It’s win-win… at least, as long I’m not the one paying for tokens.

My coworkers are now talking about “loops” as a technique for getting better outputs from LLMs. This unlikely buzzword is the current stalwart defender of the AI hype fortress, its predecessors — “prompt engineering,” “MCP,” “skills,” “context engineering,” “harness engineering” — littering the field like so many corpses. These techniques didn’t fix the problems of “hallucinations” or “misalignment,” and I would bet money that “loops” won’t magically fix everything either. I predict they will cost a lot of tokens, though.

But again, this is all a lot of fun, and that is the reason we’re doing it. That’s why we’re riding around this buzzword carousel again and again. Not because it makes us faster or more productive. Not because we write better code this way. Not because the software that comes out is better. Not because there’s any ROI. Because it’s fun.

Everyone I’ve talked to who is using AI has confirmed this, in the end. I ask probing questions about what techniques they’re using, what benefits they’re getting, what the quality of the resulting software is, and how long it takes to fix the issues, and eventually they admit it: “it’s just more fun to do it this way.”

And that ends the conversation. For fun is beyond critique, beyond reason, beyond all economic analysis. It is unanswerable and unassailable. Fun will stand forever; it will triumph in every debate; it will still be undefeated when the last lights of our civilization wink out.

How much longer will our employers foot the bill for fun? Are they going to just let us have fun forever? When they cut off the infinite supply of tokens, will we still know how to program? Will any of our software still work? And how long will it take us to clean up the mess the LLMs left behind?

How much value are we willing to destroy in the name of having fun?

empirical (adj.)

1. Pertaining to or based on experience, as opposed to theory.

2. Pertaining to, derived from, or testable by observations made using the physical senses or using instruments which extend the senses.

3. Verifiable by means of scientific experimentation.

—Wiktionary

Sometimes I do test-driven development, and sometimes I don’t. But no matter what process I’m using to write code, I want to stay grounded in reality, by getting frequent, low-latency feedback on my work. TDD is one way to bring empiricism into software development, and I think it’s the best way in many cases, but it’s not the only way.

Here are six questions I ask myself as I’m working — on code or anything else. These are the questions that ground an empirical development process.

• What problem are we solving?

• What is the baseline? What are we comparing our solution to?

• How do we know the problem is actually a problem?

• How will we know when the problem is solved?

• Is there a cheaper solution to this problem, and only this problem?

• How much do we trust our techniques for answering these questions?

I don’t always have perfectly articulated answers to these questions. But by asking them, and always looking out for better answers, I keep myself from going too far off the rails.

What problem are we solving?

In other words, what’s the goal? Why are we working on the system at all?

This seems like it should be a simple question to answer, but often, software gets written even though no one can clearly articulate what problem it’s meant to address.

Step 1 is to say, “I am solving this problem. The problem is X and therefore we’re going to do Y.” I have seen so much software made where no one ever said that. No one ever wrote that down. And then we have a whole system, and no one ever said what problem it’s supposed to solve. If we’re not solving problems, I have no idea why we’re in this room.

—Rich Hickey

Be honest in your answer to this question. Any attempt to prevaricate will get shot down by the next question in this sequence, so just be real.

Honest answers might include:

• “This project idea is burning a hole in my brain and I can’t think about anything else.”

• “I just want to learn Kotlin, and this is one way to do that.”

• “We need to migrate to Next.js because it might solve all our infrastructure problems, and devs are complaining about legacy code, and oh god I just don’t know what else to try. At least if we switch we’ll be able to say we’re using a modern JS framework.”

These are not necessarily bad answers. In the right context, they might represent problems worth solving!

More typical answers might include:

• “We’re fixing this bug — here are the repro steps.”

• “We’re implementing password reset for users with email addresses.”

• “We’re improving performance.”

• “We’re tidying up this messy function.”

What is the baseline?

In other words, what are we comparing our solution to?

In many cases, the answer to this question is self-evident: the baseline for our work is the current state of the system.

In other cases, especially when starting a new project, the baseline isn’t obvious and needs to be stated. For example, if you say “I want to write a high-performance statistics library,” the next question you should be prepared to answer is “high-performance compared to what?” What’s the fastest library out there right now? What are you trying to compete against?

Answering this question can change how you look at the problem. Maybe it turns out that there is a very fast library already available, but it doesn’t have all the features you need, or it’s poorly documented, or the API sucks. In that case, performance might not be the right focus! Maybe you can wrap the existing library in a better API, and thus solve the real problem.

How do we know the problem is actually a problem?

This is the step that many programmers skip — and TDD stops you from skipping it. It’s all too easy to see a “bug” in code you just typed and swat it immediately, before you verify that it is a bug, and not just a piece of lint.

If you think there’s a case where the code won’t behave correctly, consider proving so with a test before you change it. If you don’t do this, at best the code will be more complicated than it needs to be. At worst, you might introduce new bugs that weren’t there in the simple code!

How will we know when the problem is solved?

This is another question that TDD answers for us. If we pinned down the problem with a test, then the problem is solved when the test passes.

In the absence of TDD, we should always have some way to get feedback on our work and verify that it had the desired effect. Maybe that feedback comes from other programmers, or QA, or even users — but it has to come somehow.

Is there a cheaper solution to this problem, and only this problem?

This question steers us away from writing unnecessary code, or doing any other unnecessary work. I do not mean to imply that less code is always better. Rather, easier-to-write code is better, other things being equal. Don’t reject the quick and dirty solution until you know it isn’t good enough.

The pedantic way to answer this question is to write the quick and dirty code first, and then to identify everything that’s wrong with it and to fix those problems one at a time. Quick and dirty solutions often have many problems: they might be hard to understand, or might have performance or security issues. The point is, the new problems are separate from our original one. By taking one problem at a time, we ensure we’re solving real problems, and not imaginary ones.

However, the pedantic way is not the only way. Sometimes, you can foresee in advance of coding that the cheap solution will be irreparably bad in some way, and will need to be ripped out and rewritten. In that case, there’s no reason to write the cheap code. Just fix the problem “in the design phase.” Whether to do this is a judgment call — as is everything.

How much do we trust our techniques for answering these questions?

If we’re relying on tests to tell us if our software works, our confidence in the code is limited by our confidence in the tests. That can be problematic, because tests aren’t perfect. Tests can be invalidated by mistakes in setup or assertions. And no matter how many tests we write, there will always be gaps where bugs can sneak through.

Every software verification technique has limits. This is true of static types and code review as well as tests. We can try to compensate for the weaknesses of each technique by using them in combination, and that often works very well, but we’ll never reach perfection.

I don’t worry about this too much. That’s because there are no wrong answers to the questions I’ve listed here. There’s no need to reach for some unattainable, perfect process. The important thing is to keep asking yourself the questions, and to trust that with enough repetition, your process for answering them will improve.

Two kinds of defects

We can divide software defects into two broad categories: on one hand are behavioral defects — what we often call “bugs.” On the other hand are structural defects. Bugs are apparent to users of the software, but structural defects are usually invisible to everyone but the programmers. Structural defects make the software more difficult to change.

Crucially, the changes impeded by bad structure include changes to improve structure! Structural quality is therefore caught in a reinforcing feedback loop:

The good news is, this loop, like all reinforcing loops, works both ways. Improvements to structural quality make further improvements easier. They also make it easier to improve behavioral quality, i.e. to fix bugs or add features.

A thought experiment

Imagine two software systems, A and B. They have the same set of features, but:

• System A has a clear, simple structure that’s an excellent fit for its purpose. Unfortunately, there are logical errors in the code that cause it to produce incorrect results.

• System B has no known bugs, and always produces correct results. Unfortunately, it has an overcomplicated structure that obscures the mechanism by which it produces those results.

Ignore, for now, whether these systems could or would ever be built as described. The question is, which one would you rather own?

If you aren’t ever going to change the software, you’ll answer “System B.” But of course, that’s silly. Software always needs to change.1 And it will be much easier to fix the bugs in System A than it will be to fix the structure of System B to the point where you can develop new features safely. System A is almost certainly the better long-term choice.

How it goes in reality

In the real world, of course, we aren’t given a choice between System A and System B. Structure and behavior evolve together, and bugs tend to crop up when and where the structure gets confusing. We tend to find that systems either have both good structure and good behavior, or bad structure and bad behavior.

What I’d like you to take away from this post, then, is this: efforts to fix bugs will be largely vain in the face of bad structure. When you find yourself facing a slew of bug reports, don’t focus on squashing the individual bugs. Try to understand the code first. In order to understand it, you may have to start improving the structure. Get the structural problems under control; then the bugs will pack up and leave on their own.

What's the value of that last 0.1%?

• It will save you from a debugging nightmare later, when users report problems that you can't reproduce or diagnose.

• It will prevent service outages from happening if/when the system changes so the 0.1% case is now a 10% case.

• It will avoid contaminating your data with anomalies that downstream consumers will have to patch up, filter out, or (most likely) handle incorrectly — which would create bigger problems further downstream.

• It will save your support team time. If your code serves a million requests per day, that one-in-a-thousand bug is going to affect a thousand people every day. A few of those people are likely to call support.

• It will save your users time. Humans have terrible intuition about orders of magnitude, so do the math. If the bug affects 1000 people per day, and each person spends a minute working around your bug, that's equal to two 8-hour workdays wasted. Every day.

• It will keep your error logs quiet, so you can quickly spot and fix unexpected errors instead of being distracted by expected errors.

Finally, and most importantly — it's just the right thing to do. You and your users both deserve code that works.

Oh, come on, Ben. If it were as easy as saying "just don't write bugs," software wouldn't have any bugs.

True, we can't foresee and prevent all bugs. But we can foresee some bugs. (like the one I was about to write, when I started writing this post instead!)

Sometimes, we know what the "right way" is, but the "wrong way" is just so tempting. My goal in writing this post is to make it seem less tempting.

.

The product manager records the feature request in our backlog, prioritizes it relative to the other feature requests, and we build it when it becomes the top priority.

Our work is straightforward; the user is (eventually) satisfied. Peace and order reign in the land.

Now, what happens when we want to remove a feature to simplify our code? Or, more generally, make breaking changes to an existing feature?

Now, rather than users asking us (the engineering team) to change, we're asking them to change. This is much harder.

Why is it harder? Well, there's one engineering team, but there's probably not just one user. Any feature that we build has a large audience, and is inevitably going to accumulate many different users.

Trying to get many users to change how they do things is much harder than getting one engineering team to change something. It's a simple matter of scale.

There's also the question of who is paying whom for their work. Programmers don't pay users to adapt to breaking changes. Your users might tolerate having to do a little bit of work in exchange for the ability to keep using the software, but it won’t make them happier.

Finally, the fact that breaking changes are usually motivated by technical needs rather than business needs makes it hard to get buy-in from all stakeholders. Your users have their own backlog of work they need to get done; they're not eager to add "adapting to a breaking API change" to their to-do list. If users drag their feet, who will you escalate to? Will you be able to make the case for your API change to your manager’s manager? What’s the actual business reason to drop support for the old API?

The consequence of all these factors is that it's easy to add features to software, but difficult to remove them. Every feature you add is, in effect, a promise to your users that you'll maintain that feature. It's easy to make promises, harder to keep them, and painful to break them.

Questions to ponder

• How might we prevent users from coupling their code to internal implementation details of our system that we want to be able to change later?

• How might we give users what they need without over-promising (i.e. exposing extra APIs and data that they don't need)?

• When we need to make breaking changes, how might we keep the old API available while users are switching over to the new one?

• Incrementally adding a bunch of special-purpose APIs creates its own kind of mess. Are there design principles that can help us get a general-purpose API right the first time around?

• Even if we can't get it right the first time, are there principles that could help us get it wrong in a way that can be made righter without any breaking changes?

a purposeful gap of unreadiness between two points of readiness on some system’s timeline, a before point and an after point.

The system starts ready, and it ends ready, and the step is that period during which it’s not ready.

This definition is precise, but pretty abstract, so today I'd like to talk about what steps mean to me in practice.

An Example

Say we’ve just created a brand new file and rolled up our sleeves to write some TypeScript. The system is in a ready state, because an empty file is perfectly valid, runnable TS, even though it doesn’t do anything.

I’ll represent this ready state as a blue-green square.

Now we want to import our test framework so we can do some TDD. By the time we’ve typed

import

our system is no longer ready. This isn’t syntactically valid TypeScript, because import is a keyword and needs to be followed by whatever we’re importing. At this point, we’ve taken half a step. We’re up in the air.

We finish typing the import statement, and we’re back on solid ground again. Ahhh. Relief. That’s one step.

import {test, expect, is} from "@benchristel/taste"

We take a few more steps of this kind, completing our first test:

import {test, expect, is} from "@benchristel/taste"

test("a Calculator", {
  "initially displays 0"() {
    const calculator = new Calculator()
    expect(calculator.display(), is, "0")
  },
})

But now, a funny thing happens. We’re in a syntactically valid state, but our code doesn’t typecheck, because Calculator is not defined. Although we’ve taken many steps at the syntactic level, we’re now just halfway through a step at a higher level — the level of types.

There are a few ways we could get back to green, but the quickest is probably to define Calculator in our current file.

import {test, expect, is} from "@benchristel/taste"

class Calculator {}

test("a Calculator", {
  "initially displays 0"() {
    const calculator = new Calculator()
    expect(calculator.display(), is, "0")
  },
})

The typechecker still isn’t happy, because there’s no display() method. Let’s add that.

import {test, expect, is} from "@benchristel/taste"

class Calculator {
  display() {}
}

test("a Calculator", {
  "initially displays 0"() {
    const calculator = new Calculator()
    expect(calculator.display(), is, "0")
  },
})

And now, both the parser and the typechecker are happy. Step complete!

…except, the test fails.

Getting the tests to pass is pretty easy: return “0”. I’m getting kind of tired of drawing these pictures, but here’s a final view of our journey from green to green.

Debrief

I think you get the idea. We take steps at multiple levels of scale, using multiple layers of verification that tell us how “ready” we are to ship software.1 The smallest scale, and the most primitive type of verification, is syntax checking, and at that level we can flicker back and forth between ready and unready many times per minute. The next smallest scale (in static languages) is typechecking or compilation. It takes a bit longer to go from green to green at that level. Then come tests, and perhaps linting, and beyond that commit-readiness, integration-readiness, and release-readiness. We’re not “ready ready” until every level is green.

The point

The smaller we make our steps, the smoother and safer our work becomes. Smooth and safe are prerequisites for fast. This is true at all levels of scale.

When we’re halfway through a step, in the unready state, we’re a lot less maneuverable. Changing course is risky because the unfinished work is likely to get in our way and trip us up. In the ready state, we have a chance to get our bearings and figure out which direction to go next. If we don’t get back to ready frequently, it’s easy to get lost.

We’ve all experienced what happens when we get too far from “ready,” e.g. when we spend half an hour typing without ever stopping to compile. When we finally decide to run the code, we get: Syntax error. Syntax error. Type error. Syntax error. Type error. Oh, look, all the tests fail. In the best case, we spend a lot of time debugging. In the worst case, we decide the mess is too big to clean up, and we throw away our changes and start over.

Note: starting over isn’t always a bad thing; sometimes we “plan to throw one away” (as Fred Brooks put it) to learn more about the problem we’re solving. But wandering away from “ready” and getting lost in the weeds isn’t a strategic sacrifice; it’s just a blunder.

A similar problem can happen at the larger scales of software development. If you spend too long working on a feature without getting feedback from potential users, you’re liable to build something they don’t even want.

Keep your steps small, at every level of scale, and you’ll be a happier, more productive programmer.

My last few posts have been about the patterns and techniques I use when setting up a new software project:

• Walking Skeleton

• Entrypoint Document

• Readme-Driven Development

• Diamond Design, Part 1 and Part 2.

Continuing the theme, I want to write about how to start testing a project. The summary is, I tend to start with manual system testing of a walking skeleton. As the software begins to develop real functionality, I’ll scaffold each new class and function with unit tests. Once the project has hit a self-sustaining rhythm, I’ll automate some of the system testing, but put almost all my weight on unit tests.

In order to make it fully clear what all of that means, I’m going to have to provide some definitions. That’s what this post is all about!

What is a unit test?

“Unit test” has got to be one of the most maligned, misunderstood, and variously defined terms in our industry. Matt K. Parker has written a bit about the term’s origins in the Smalltalk test framework SUnit:

One of the primary goals of SUnit was that each test could run in isolation from all of the other tests. In other words, a “unit test” is a test that’s isolated from all of the other tests in the test suite. The “unit” is the test itself!

“Isolated” means a test’s setup should not depend on other tests having been run before it. Each test should start from a clean slate and do its own setup. Nor should a test interfere with other tests that might run afterward. Tests should be good citizens and clean up after themselves (or not make a mess to begin with).

I think test isolation is a great idea! But I have a problem with equating “unit test” with “isolated test.” Really, all tests benefit from isolation. The world has moved on since SUnit, and these days, test isolation goes without saying. In a modern software dev shop, the original definition of “unit test” is so all-encompassing as to be useless.

Moreover, while I think originalist definitions like this one can be illuminating, they’re not the end of the story. “Unit test” has a colloquial meaning, which has diverged considerably from the original definition. That’s the definition I want to talk about today.1

Here it is:

One thing I like about this definition is how simple and unambiguous it is. Is your test file importing production functions and classes and doing mad science on them? If so, it’s a unit test.

I know some people are going to disagree with me on this one. In particular, you’ll notice that my definition fails to distinguish between integrated tests and unit tests. To save you time, here are my counterarguments to the other defintions of “unit test” I’ve seen. Please direct your annoyance toward the comments section!

System tests

If your test file doesn’t import production code, it’s not a unit test. So what is it? A system test.

System tests, as the name suggests, interact with a whole (installed or deployed) software system. They simulate actions a user might take: clicking on things and entering data (in the case of a website or GUI app), running commands (in the case of a CLI) or making API calls (in the case of a web service). Other names for system tests include “end-to-end tests” and “integration (or integrated) tests,” though the latter term is ambiguous.2

One neat thing about system tests is that, because they interact with the system through an externally-visible interface, they don’t have to be written in the same language as the production code. There are many system testing frameworks and domain-specific languages available, especially for GUI testing. One I’ve used recently is Cypress; I’m also interested in Playwright. For system testing CLIs, Samir Talwar has created Smoke.

What about system-testing a library? At first glance, it might seem like libraries only need unit tests. After all, their clients are going to be calling them in-process, so in-process unit tests should be perfectly adequate. However, there is also the question of testing the library’s installer, packaging, or configuration. For that, you’ll want some system tests that create a new project (e.g. via npm init in NodeJS), install the library in it, and confirm that the library can be used.

System testing tends to involve more complex infrastructure than unit testing. One of the first problems you’ll run into is that you need an automated way to compile a complete, usable build of your software (though not necessarily a production build) and put it somewhere another program can get at it. Often, this means installing it in some kind of sandboxed local environment specific to the test run. “Sandboxing” means the installation shares nothing with other installations. That way, different runs of the tests don’t interfere with each other (see the discussion on test isolation above), and you know exactly what code you’re testing.

Setting up the infrastructure to do this is an investment that will pay dividends. The ability to create sandboxed installations of your software is valuable even if you’re not doing automated system testing. For example, you’ll often want to have a dev build of your software installed alongside the “real” version that you use day-to-day (you do use your own software, right?) and sandboxed installations make that easy. Setting up a project with automated system tests thus makes manual testing easier too.

Speaking of which…

Manual system testing

So far, I’ve been writing as if all tests are automated. But manual testing exists too, and in many cases, its benefits outweigh its costs.

One advantage of manual testing is that it lacks the main disadvantages of automated system tests, which tend to be flaky and brittle. “Flaky” means they fail intermittently, in ways that appear nondeterministic. “Brittle” means they’re prone to failing when you make some innocuous change to the code, like swapping the order of two buttons. There are ways to write system tests that minimize these problems, but you can’t completely solve them. By contrast, manual testing is more resilient to change and disturbance in the system.

A second downside of automated system tests is that, while they can catch functional problems, they can’t alert you when your UI fails to be understandable, usable, or attractive. The presence or absence of these hard-to-quantify attributes can only be discovered by a human who is actually trying to use the software.

For all these reasons, I prefer to do most of my GUI testing manually. In future posts, I’ll talk about the techniques I use to make this feasible. For now, here’s the gist:

• I write UI code in an MVC (model-view-controller) style — separating the logic and state of the UI (the model) from how it’s presented to users (the view).

• Because the model knows nothing about the DOM or the UI framework I’m using, it’s easy to unit test. That’s good, because the model contains all the complicated, test-worthy logic.

• The view code is extremely simple — “too simple to break.” It’s usually little more than an HTML template with slots for data, and doesn’t need unit tests.

• I manually test the UI whenever I make changes to the view.

• I sometimes use image-based snapshot testing to catch unintended visual changes. Chromatic is a service that will do this for you.

Manual unit testing?

So far, we’ve covered automated unit tests, automated system tests, and manual system tests. Are there manual unit tests? How would that even work?

Perhaps REPL-driven development or “live programming” could be viewed as a type of manual unit testing. In this style of development, you write code in an interactive prompt (a REPL or read-eval-print loop), calling each new function to check that it’s doing what you expect.

I don’t have much experience with REPL-driven development. It appears to be most popular among Lisp and Clojure programmers. If you know something about it, I’d love to hear your recommendations for where I could learn more!

Wrap-up

We’ve talked about two dimensions along which tests vary:

• Manual vs. automated

• System vs. unit

A unit test is any test that runs in the same OS process as the code it’s testing, and calls that code directly. A system test interacts with a whole software system the way a user or client would.

When I’m starting a new project, I begin with manual system testing. The software’s tiny and cute, so it starts up fast, and there’s not much to test. As the software grows, I add unit tests for much of the new code. Referring back to my posts on Diamond Design, I will unit test all code in these facets:

• domain/

• platform/

• lib/

I often skip unit testing in the fourth facet, app/. Instead, I keep app/ as simple as possible, preferring to push complexity into the other facets and under the microscope lens of unit tests. When I make changes to app/, I manually test them through the UI.

Sooner or later, all that manual testing starts to feel repetitive. At that point, I automate the drudgery with system tests. However, I’ll continue manual testing throughout the project, looking for visual bugs and user experience issues.

Overall, I have found that this approach to testing is easy to get started, scales well to large projects (> 1 million lines) and, in conjuction with the other techniques I describe in this newsletter, is capable of producing nearly bug-free software. If you’d like to hear more about how I write code, feel free to subscribe!

Subscribe now

• I briefly imagine the effects of the first option. What will happen if I do A? What will future me, future them, future us experience? I consider the good effects as well as the bad, trying to conceptualize them as a whole. What will it be like to live in that world?

• Then, in the same way, I imagine the effects of the second option. What will the world be like if I do B?

• Then I pick the option whose effects I’d rather live with.

That’s it!

Ben, this is just pros and cons lists. It’s like, the oldest decision-making trick in the book.

Yes, but. There’s some additional nuance here.

First of all, I almost never write down the pros and cons. There are a few reasons for that.

• I use this technique hundreds of times per day — literally every time I make a decision. I couldn’t get anything done if I paused to make a list each time.

• I use this technique for tiny decisions. What should I name this test? How should I phrase this sentence? Should I put a blank line here or there? In what order should I do these 3 operations?

• The effects of a decision are not certain. Some are likely to occur, some unlikely. Also, magnitudes like cost or effort have a confidence interval. But trying to put a number on probabilities and confidence intervals is a distraction.

• The effects of a decision are, in general, far too numerous to list.

• Presupposing that any given effect is a pro or a con is unnecessary and confusing. To know whether something is good or bad, you may have to look at the larger context. That’s why I avoid focusing on individual effects and instead consider each bundle of effects as a whole.

• I might not be willing to admit in writing how much certain effects matter to me. “I want to use pnpm instead of npm as my package manager because I’m afraid people will make fun of me for using npm.” That statement probably won’t appear on my pros/cons list, but it might be a factor in my decision.

I also don’t think through every effect consciously and intellectually. The way I experience this technique subjectively is that I hold a decision in mind, and then the effects briefly flicker through consciousness, as subconscious mental processes return their predictions. Sometimes I double-check those predictions, but most of the time I just trust my subconscious. It’s pretty good at what it does. Yes, sometimes the predictions are wrong — then I admit my mistake and learn from it.

It’s not as easy as it looks

The subjective experience I described above is probably something akin to “mastery.” One does not simply decide to adopt this process. First, you have to train your subconscious mind to predict the effects of tiny programming decisions, and that takes practice. In particular, it requires experience making decisions and then living with their results.

Good judgment comes from experience, and experience comes from bad judgment.

(variously attributed)

I highly recommend watching Kathy Sierra’s video about “Making Badass Developers” if you want to learn more about how this kind of training works. You can learn to make decisions this way, if you put in the hours of deliberate practice.

Needless to say, you also need both empathy and accountability for this process to produce anything close to globally-optimal decisions. (Hopefully this is obvious, but I felt the need to stick this disclaimer in somewhere.)

Why this post?

I decided to write this post because I think some of my past posts (especially the CEVICHE one) implied that I have a very rational, goal-directed design process, and that just isn’t the case.

I’ve written briefly about my actual process before, but it was buried in the middle of a long post. I thought repeating the idea here might help clarify things.

This is the need that I constantly return to when creating software. Whenever I am thinking about what to do and how to do it, I always evaluate the result (or my guess at what the result will be) by the life that it creates. By which I mean: is the resulting interaction more pleasant than the status quo? Or, more profoundly: does it make me feel more alive, more of a person, more connected to the work, more truly at ease being myself?

Recap

In part 1, we discussed the app/ and lib/ folders, which form the top and bottom “layers” of our program. lib/ is at the bottom and can’t call any of the other layers. app/ is at the top and contains the glue and user interface code that holds everything else together.

In this post, we’ll cover the stuff in the middle: domain/ and platform/.

Errata in Part 1

Ignore the stuff I wrote about code organization within subfolders of app/ and lib/. My actual codebases break these “rules” all the time, and I’m not sure how valuable they are even as general guidelines. I’ll need to think about this topic a bit more.

Domain and business logic

Domain logic is the core of our application. Domain code is arguably the most important code we write, because it defines the concepts and behavior that users care about.

In a music production app, the domain code talks about tracks, notes, instruments, and samples. In a financial planning app, it’s all about currencies, budgets, interest rates, and stocks. In a language-learning app’s domain code, you’ll find vocabulary, lessons, spaced repetition strategies, and practice exercises.

Domain code is platform-agnostic. It doesn’t know or care where our code runs (a web browser? a smart TV?) or how it presents itself to users (a command line interface? A GUI?) It can get away with that because it just defines data types and the operations on those types.1 It doesn’t know about the user interface or about data persistence.

Some people like to distinguish “domain logic” from “business logic.” AFAIK, the difference is that domain code concerns itself with what is logically possible, while business code concerns itself with what is allowed by policy. For example, in a social media app, the statement “A follows relationship is between two accounts, the follower and the followee” describes the domain, while “A user can follow no more than 500 accounts” describes a business rule.

If we wanted to uphold this distinction in code, the “follows” relationship would be implemented in domain/, while the 500-followees limit could be implemented in app/ (possibly in a web controller or service layer) or possibly in its own business/ layer between app/ and domain/. I’ve never bothered making this distinction in my programs, though, and can’t say I have a strong (or particularly informed) opinion about it.

Platform code

Now let’s switch gears and talk about platform code. Platform code is the polar opposite of domain code. Just as domain code knows nothing about the platform, platform code knows nothing about the domain. That enables it to be reused between applications with different domains.

I define “platform code” as encompassing everything that

• makes the program available to users: the UI technology, the installer, the web framework, etc.

• connects the program to the real world, via effects.

Examples of platform code include:

• The event loop for a GUI app or game

• Routines for reading and writing files

• A SQL query builder

• A web server framework

• A suite of React components implementing your company’s design system.

Why separate platform code from domain code? One reason is to ensure that your most valuable code — your domain code — is platform independent. Platform independence gives you amazing flexibility. It’s why, for instance, the TypeScript compiler can run in a web browser, even though it “normally” reads code from a filesystem. The part of the code that knows about filesystems is strictly separated from the part that knows about TypeScript syntax and semantics, allowing the second part to run without the first.

Summary

Here’s another visual summary of the different types of code in diamond design:

Why diamond design?

There are several reasons you might choose to adopt something like diamond design in your applications. I’ll briefly touch on a few of them here.

Encoding knowledge

I have come to see software development as a special case of “teaching systems how to do things.” Whenever I learn something or figure out how to do something, I want to put that knowledge into the system — encode it into the system — so that the system as a whole will remember how to do the thing I just did even after I’m gone.

Elsewhere, I wrote,

To build steadily on our abilities, step by step — that is the goal of engineering.

The idea of “building on our (collective) abilities” implies a shared pool of knowledge from which we can draw. In order for this knowledge to be legible and reusable, it has to be organized. Diamond design provides that organization.

Suppose, for example, that I figure out a neat way to solve some platform-level problem, e.g. making paginated database queries. If I then encode that knowledge so the platform-level logic is intertwined with application-specific code, I’ve missed an opportunity. No one else can reuse my code as-is, and it may take some effort to reverse-engineer my discovery. Although I’ve solved my immediate problem, I’ve failed to expand the system’s capability to solve future problems.

If, on the other hand, I carefully separate the different types of code, each part becomes easier to understand and reuse. The system is then better able to adapt to new needs.

Work styles

Each type of code in Diamond Design benefits from different techniques, different views, and even different attitudes. Separating them gives programmers a clearer sense of how to behave around each type of code.

• App code tends to be “move fast and break things.” Nothing else depends on it, so it’s free to change. Lib code, by contrast, needs to be “slow and solid,” because it’s the foundation for everything else.

• Platform and app code can be hard to unit-test due to their effects, so they must be kept “too simple to break.” Type checkers can help seal the testing gap, by verifying that app code wires its dependencies together correctly.

• Domain code, on the other hand, can and should be thoroughly tested. It might also benefit from review by nontechnical folks. To hear Scott Wlaschin tell it, domain experts are often perfectly capable of pointing out bugs in a set of F# type definitions.

Bonus facet: formats/

The four-way distinction between app, domain, platform and lib code makes for pretty pictures, but in practice I have found myself adding a fifth category, for code that deals with serialized (i.e. stringified or binary) data representations which are persisted to disk or sent between processes.

Here’s how formats/ fits into the picture:

Code in formats/ consists of pure functions, without effects. These functions are of two types: parsers and formatters. Parsers take the serialized representation and convert it to the in-memory domain/ model. Formatters go the other way.

“Why not just use JSON.parse()?” you might be thinking. And you have a point. When a program is new, there’s little motivation to create bespoke parsers and formatters. You just use whatever facilities your language has built in to convert your domain objects to and from a serialized format and that’s that.

But what happens when the domain model changes, e.g. to add a new field to an object? When you parse data created by old versions of your program, that field will be null. So you’ll have to change your code to handle nulls.

It’s easy enough to give a missing field a default value, but you want to have a central place for the logic. Otherwise, it will get duplicated all over your codebase and create a mess. The formats/ facet is that central place. As your data format accumulates more changes, you’ll probably end up wanting a versioning system, and the ability to migrate old versions of the format to the latest. formats/ is the place to deal with all that.

The overall purpose of formats/ is to shield your domain model from the grimy details of persistence, and ensure that it does not need to battle the ghosts of its past selves in the form of legacy data. You want your domain code clean and pristine, and formats/ allows it to be so.

A common mistake with formats/ is to make the domain code depend on the formatting code instead of the other way around. That compromises the purity of the domain code, though, and complicates things if you ever have multiple formats you need to write. So it’s better to arrange things as in the diagram above.

You probably won’t need formats/ if all your data is in a relational database you can run migrations on. If it’s stored in files, though, or a NoSQL database, you’ll need parsers and formatters sooner or later.

What am I missing?

As I mentioned, Diamond Design is only a half-baked idea, and I’d love to hear your feedback and suggestions. How do you organize your code? Let me know in the comments (on substack) or in reply to this email (if you’re reading this as an email).

• You can more easily see how the larger centers relate (e.g. through imports) and how centers in the same file cohere.

• You don’t get distracted by extraneous code as you’re programming.

Once you start creating multiple files, though, you have to answer some hard questions. What should the files be called? How should they be organized?

In this post, I want to talk about my current “Platonic ideal” of how to organize application source code, which for the purposes of this post I’ll call diamond design. Diamond design organizes code into four “facets:”

• Product-specific code

• Domain and business logic

• Platform code

• Library code

In this post, we’ll cover product-specific and library code.

“Diamond design” is a work in progress

The ideas in this post are likely to undergo revision over the next few years. One sign: while I’ve tried to employ this organization scheme on several projects, I haven’t adhered to it exactly on any of them. Maybe the concept is fundamentally flawed, or maybe reality is just too messy for any rigid organization scheme to work perfectly. In any case, use these ideas with caution, adapt them to your context, and expect change.

I’m publishing this post anyway, in the hope of clarifying my own thoughts and getting feedback. If you figure out a variant of diamond design that works better, I’d love to hear about it!

Product-specific code

Product-specific means the code knows about both…

• the platform, i.e. how your product is delivered to users (Is it a web app? A command line tool? A mobile game? A GraphQL API? A browser extension?)

• the domain, i.e. what the product is “about.” (Music production? Graphic design? Finance? Dungeons and Dragons?)

Product-specific code is the glue that holds these other facets together. It generally includes the entrypoint (main()), any application frameworks, installers, or other scaffolding, the user interface, and possibly other stuff.

Product-specific code depends on and connects every other part of your program. Because it depends on so many things, it is constantly changing.1 If not managed carefully, these dependencies make it complex, hard to reason about, and hard to test.

In spite of these downsides, the great majority of application code is product-specific. That’s probably inevitable to some extent — gluing a domain to a user interface just seems to require a lot of words somehow. Still, “big” is not the same thing as “complicated,” and it’s complexity that really hurts. The purpose of diamond design is to reduce the complexity of product-specific code as much as possible, by moving logic into the other facets. The hypothesis (supported by my experience) is that this will result in a system that is easier to maintain and improve.

Naming

I typically put product-specific code in a folder called app/. Not the most creative, I know. But it gets the job done.

Organizing product-specific code

Since product-specific code tends to be bulky, it is likely to need some amount of internal organization. We can apply a simple principle here:

• Things that change together should live together.

• Things that change at different times, at different rates, or for different reasons should live apart.

I remember hearing this advice from Sandi Metz, though I don’t have the exact source handy. The reason we want things that change together to live together is simple: it makes it easier to find the code you have to change. Plus, if you want to cleanly remove a feature (something I suspect software companies will be doing a lot of in a few years) it’s much easier to do if all the code is in one folder.

This is an argument against the Ruby on Rails approach of e.g. having separate folders for models, controllers, and views. You’re rarely going to change all of your models at the same time, or all your controllers at the same time. But almost every feature you build will touch a model, a controller, and a view.

Therefore, if you want changes to cluster, it’s better to have a separate folder per feature, or per page. You might, for example, have a bunch of code related to logging in and out, resetting passwords, and so on. That can go in login/. The code for user settings can go in settings/. The code for discussion posts can go in discussions/. Et cetera.

What about code that’s used by multiple features? Well, maybe you need an app/shared/ directory… but quite possibly that code shouldn’t go in app/ at all. Remember, there are three other facets of the diamond we haven’t even talked about yet! So let’s look at those alternatives.

Library code

We can go to the opposite extreme from app-specific code and write code that is coupled to neither our domain nor our platform. That’s library code. Library functions often deal with language-level primitives (e.g. strings and arrays) or open standards (e.g. JSON).

Elephant in the room: why can’t we use a third-party library? Why can’t we use the standard library that comes with the programming language?

If you can get the code you need that way, go ahead and do it. But:

• If you’re shopping for third-party libraries: beware of supply-chain attacks. Choose libraries with few or no dependencies of their own. Choose something that’s been around long enough to have a track record. Check that the maintainer’s incentives align reasonably well with yours. Installing a library is a bigger commitment than most people realize, and an NPM package that someone wrote in a weekend and abandoned is probably not something you want to marry your application to.

• If you’re using the standard library: consider whether your application code could express itself more eloquently in terms of a simpler abstraction or a differently-shaped API. Standard libraries often prioritize exposing low-level functionality over ergonomics — sometimes for performance reasons, sometimes because the general problem really is that complicated.2 You know your needs better, and can build a library that’s just right for you.

When neither the standard library nor a third-party library will fit your needs, you need a place to put your own internal library code. This facet gives you a place.

Here’s an example of when you might write library code: in JavaScript, there’s no built-in function to find all occurrences of one string within another. Weird, right? It seems like that would be a pretty commonly-used function. If you want it, though, you’ll have to write it yourself.

// I, Ben Christel, am the author of this code block.
// I hereby release it into the public domain.

const NOT_FOUND_INDEX = -1

/**
 * Finds each occurrence of `needle` in `haystack`.
 *
 * @yields each index within `haystack` at which an occurrence of
 * `needle` starts. Occurrences can overlap. Indices are yielded in
 * ascending order.
 */
function *indicesOf(needle, haystack) {
  for (let i = 0; i <= haystack.length; i++) {
    i = haystack.indexOf(needle, i)
    if (i === NOT_FOUND_INDEX) {
      break
    }
    yield i
  }
}

When you write functions like this, you should put them in an easily-findable place separate from the rest of your code. The reason is simple: someday, someone else is going to want that indicesOf function you just wrote, and if they can’t find it they’re going to implement it all over again. If, on the other hand, they can easily find it by browsing src/lib/strings.js, they’ll be delighted. Even if the function they want turns out to be slightly different from the one you wrote (maybe they need nonOverlappingIndicesOf or reverseIndicesOf), seeing your code will ease the task of writing their own.

A word of caution: “library code” is not equivalent to the notorious utils/ folder. When I say “library code,” I’m using that as shorthand for code that…

• is domain- and platform-agnostic

• manipulates language primitives (strings, arrays), open standards (URLs, XML, JSON Schema), or other ubiquitous concepts (e.g. dates and times, or geospatial data)

Here’s the litmus test for deciding whether something is library code. When you look at just that code in isolation, can you tell what application it’s from? Can you infer anything about the domain, or the kind of program it is, whether it’s a web service or a Minecraft mod or what? If you can, it ain’t library code. It goes in one of the other facets — probably domain/ or platform/.

Naming

I generally put library code in src/lib/. That name is confusing, though, if the project is itself a library (e.g. an NPM package) so I’ve sometimes used general-purpose/ or gp/ instead.

Organizing library code

I generally put library functions in a file named after the most structured type on which the function operates. For example, these functions operate on both numbers and strings:

function parseNumber(s: string): number | undefined

function formatNumber(x: number): string

Since numbers are “more structured” than strings, in the sense that some (but not all) strings represent numbers, but all numbers can be written as strings, the functions would live in src/lib/numbers.ts.3

Organizing library code that deals with open standards is easy: the file is named after the standard. Code that deals with URLs goes in src/lib/urls.ts.

Up next: platform and domain code

In the next post, I’ll talk about the other two facets of diamond design: platform code and domain code. Stay tuned.

(Bad Ed never spent more than a few hours in jail, of course, because how was the sheriff going to make a living if the saloon didn’t have any customers? Er, customer.)

Much like detecting crime in Two Dudes, finding bugs in a two-line codebase is easy. Debugging only becomes hard when the guilty line of code is hiding among a thousand innocent ones, and you don’t know where it’s hiding when you start investigating. You have to investigate (and reject) many more incorrect hypotheses, before you find the correct one.

This might be why programmers, on average, spend about 50% of their time debugging.1 That’s a lot! My own experience indicates that this percentage can probably be reduced significantly, and that programming becomes a lot more fun when you don’t have to debug as much.

If only all our codebases could be like Two Dudes, we’d never need a debugger. We’d never need to write another print or console.log. Of course, life can’t be that simple.

Or can it?

A zero-bug development process

If you had some way of spotting a bug immediately after writing it, you wouldn’t need a debugger. You’d know which line was guilty: it’s the line of code you just wrote. So you’d just hit ctrl+Z, undo your last change, and the bug would be gone.

It’s actually possible to work like this, as long as you:

• Maintain a complete suite of tests (or other automated verification checks) at all times.

• Derive your tests from your intentions for what the code should do, not from what it happens to do currently. Then, make the code match the tests. Not the other way around.2

• Work in very small steps.3 Keep the intervals in which your code will not compile or run very short, ideally on the order of a few seconds. Here is a tiny technique that helps with this.

• Run your tests continuously — every time your code reaches a compilable state.

Following these “zero-bug rules” ensures that you will notice most bugs as soon as you introduce them, and can revert them immediately. As a bonus, you’ll understand your code so well that any bugs that do slip through to production will be easy to diagnose. Your reaction to a bug report will be “d’oh! I should have thought of that!” instead of “that shouldn’t be possible!”

Why achieving zero bugs is hard

For many software developers, the big stumbling block is the “run your tests continuously” rule. You can’t follow this rule if your test suite takes minutes to run. You can’t even really do it if it takes 10 seconds to run. You need to aim for the Doherty threshold: feedback in 400 milliseconds or less. In future posts, I’ll talk about how to design your code so it’s possible for tests to run this quickly. For now, I’ll just assert that it’s possible.

One development process you can use to implement the zero-bug rules is test-driven development. I happen to like TDD a lot, but maybe you don’t. Fortunately for you, there are probably other possible implementations of the zero-bug rules. Maybe you’ll invent the next great one.

Further Reading

• Debugging: the biggest waste by Daniel Moka

My first forays into programming, in middle school and high school, were in the domain of computer games — written in Visual Basic, of all things. I had limited access to the family PC, so I spent a lot of time away from the computer daydreaming about the next feature I would build for this or that game.

I recorded my ideas in the form of user manuals, even going so far as to draw “screenshots” of what I imagined the UI would look like. This seemed natural to me, because at the time, a lot of games did have lavish, illustrated user manuals. Two of my favorites were the manuals for Sim City 2000 and F/A-18 Korea. These were the touchstones that I tried to emulate as I wrote detailed tutorials and reference documents for imaginary games — many of which I never actually built.

I’m sharing these memoirs in the hope of convincing you that writing documentation can be fun. In fact, if you’re not careful, it can turn into a guilty pleasure. Writing documentation for programs that don’t exist yet gives you a feeling of accomplishment for less effort than it would take to write working code. But it’s also useful: documentation helps you plan the implementation.

Your pre-implementation docs don’t have to be elaborate. In fact, it’s better if they’re not, because your plans will almost certainly change. That’s why the technique we’re discussing today is called “readme-driven development” and not “documentation-driven development.” A readme is the minimum viable documentation to get your project off the ground.

Plans are worthless, but planning is everything.

—Dwight D. Eisenhower

How to begin

README.md is often the first file I create in a new project. Before I have any code, I write a bit of prose about what exactly I’m going to build.

What goes in a readme varies by project, but I usually start with:

• An explanation of what the project is and why I’m doing it. What problem does it solve? What’s unique about it? What will make it stand out from the competition? (Technique: Say Why)

• A sketch of a user manual. How do you install the thing? What’s its public interface?

• High-level thoughts about implementation, e.g. data formats and architecture.

• Developer documentation. (See: Walking Skeleton)

Why

Starting with a readme…

• helps your team agree on what you all are going to do before you do it.

• provides the basis for a backlog of user stories.

• reveals flaws in the design early, when they’re easy to fix.

• records your ideas — they may be valuable later, even if you don’t end up implementing them in the first version.

• grounds your designs and keeps you from accidentally straying from your original vision. (You can, of course, intentionally change your vision later.)

• ensures you write documentation.

Pitfalls

Don’t fall into the trap of gold-plating your readme. Remember that it’s supposed to be concise and low-polish. Avoid getting too committed to your early plans — they will change.

Another possible failure mode is that you make plans that are so ambitious they turn out to be unimplementable. The readme-writing phase of a project is a good time to dream big, but perhaps not too big. Remember, you are going to have to build this thing. So make grand plans, by all means, but hold them very loosely. If you share the readme with people outside your immediate team, be sure to communicate that it is aspirational — a highly speculative rough draft. Put prominent notices to that effect in the readme itself.

As soon as you run into implementation difficulties, consider whether a different design would be more feasible, or whether you can ditch the feature entirely. My motto is: never hesitate to cut scope. You can always add it back later.1

Examples

Here are some first drafts of readmes I’ve written for my projects:

• mdsite

• audition

• marss

It’s fun (for me) to look back at these old readmes and see just how much has changed about the design of the programs they’re supposed to document. Half the features described in the original mdsite and audition readmes either got scrapped or were implemented differently. Even so, writing these readmes was extremely helpful for clarifying my thoughts and planning implementation.

In a few of my projects, writing the docs was the fun and valuable part, so I stopped there:

• The Verse Format

• odd

Situation: you’re writing documentation that you hope will help someone a year or more down the road.

Problem: you don’t know how to ensure this hypothetical future person will find the document you wrote.

Solution: create an entrypoint document for each major center (codebase, project, team, product, company) in your environment. The entrypoint document should consist of a short list of links to other, topical documentation. Put it in a prominent place and direct new teammates to it. That way, people will be able to find the docs they need, and you will have a framework on which to hang new documentation.

What a “prominent place” means depends on the type of center you’re documenting. If you’re writing an entrypoint for…

• an in-person team: consider hanging up a poster in the team’s workspace with a minified link.

• a distributed team: pin a post in the team’s chatroom or main communication channel. Slack now associates a “canvas” — basically a collaborative text document — with each channel, which you can use for this purpose.

• a codebase: README.md in the repository root directory.

• a part of a codebase: maybe a README.md in the relevant directory, though this can be hit-or-miss as far as finding it later goes. I wish IDEs drew your attention to this type of documentation as you browsed the code.

• a project: wherever collaboration on that project primarily happens. This might be your issue tracker, chatroom, office space, discussion forum, or GitHub repo.

• a product or company: an internal website (or maybe even a public one!) that everyone visits during new hire orientation.

A general rule: keep the documentation close to the thing it’s describing. Put it somewhere people visit often. A common antipattern is to document code in a separate CMS. This is bad because it separates the documentation from the thing being documented, making the docs harder to find and less likely to be updated.

A possible failure mode is that the entrypoint document gets way too big for anyone to comprehend. Aim for seven links on the page, plus or minus two. Keep ‘em high-level. Example:

# Welcome to <project name>!

- Emergency contact in case of a production issue: <link>
- Main chatroom (ask for help here): <link>
- Onboarding guide: <link>
- UI designs: <link>
- Issue tracker: <link>
- Codebase: <link>
- Staging server: <link>

When you create new documents, link to them somewhere in the tree rooted at the entrypoint doc, but don’t add them to the entrypoint itself. Keep the hierarchy shallow. If you have seven links on each page, then 3 levels of hierarchy have room for over 300 pages. If you need more pages than that, it’s better to increase the branching factor than to increase the tree depth.

Another possible failure mode: you end up with several entrypoint documents, with team-, project-, and code-centric links all jumbled together, and no clear source of truth. The fix is to clearly delineate what each entrypoint is for, and move links where they belong. Each entrypoint page will probably still link to the others; that’s fine.

No matter what you do, there is a chance that future generations won’t even be able to find your entrypoint document. There’s no technocratic solution to this. The ultimate source of cultural continuity is always oral tradition upheld by people and their interactions. So keep talking to each other.

Further reading

• The “strong centers” property of living structure, from Christopher Alexander.

Examples

• Pivotal Labs practices (a company-wide entrypoint)

• Arguably, my web portal page is the entrypoint document for my life. It gets away with violating the 7 +/- 2 rule because a) I am the only user, b) it has search, and c) I update it daily, so it stays fresh in my mind.

When I told Tillie that six steps seemed a lot to have to do before you begin, she said, “You must think of those six steps not as preparation for the beginning but as the beginning itself.”

—E.L. Konigsburg, The View from Saturday

It’s Day One, you’re the first engineer on the project, and you don’t have any code yet. What do you do?

Much of your time is probably going to be taken up learning about the business, the product, and the vision for the user experience. You might be interviewing prospective coworkers. You might be working with the product manager to assemble a backlog of user stories.

But when it comes to writing the first line of code, where do you start?

I like to start with a walking skeleton.

The Walking Skeleton pattern

A walking skeleton is…

• a deployable codebase

• that implements a single, trivial behavior (e.g. displaying “hello world”)

• but nevertheless integrates together all the major architectural components that you foresee in your real application (client, server, database, etc.)

The term “Walking Skeleton” was coined by Alistair Cockburn in the ‘90s, and written up on his website in 2008. Here’s how he defines the concept:

A Walking Skeleton is a tiny implementation of the system that performs a small end-to-end function. It need not use the final architecture, but it should link together the main architectural components. The architecture and the functionality can then evolve in parallel.

To this definition, I’d add a couple criteria:

• A walking skeleton should be built simply and quickly. Cockburn says it generally takes 20 minutes to 2 weeks. That sounds about right to me. You can do it even quicker with off-the-shelf project templates, but I prefer not to use those, for reasons I’ll explain in a bit.

• It should also have a full complement of tools: package manager, test suite, static analyzer, formatter, build system, etc.

Why

There are a few different reasons you might want a walking skeleton.

First, it boosts morale and sets the standard for the rest of the project. Imagine you’re starting on a new team. Would you rather find a codebase that’s tidy and well-appointed? Or a haphazard free-for-all of random hacks and one-off scripts, where everything kinda-sorta-not-really works? A walking skeleton ensures from the start that you will be on the happy path, where the code works and your tools are ready to hand.

Second, a walking skeleton minimizes the number of detours developers will have to take as they start to write features. If a developer feels inclined to write a unit test, you don’t want any obstacles in their way. The absence of a test framework is a pretty major obstacle. Having a test framework right from the get-go maximizes the chance that tests will get written.

Third, a walking skeleton guarantees that you will be able to ship software. This sounds like a trivial thing, but it’s amazing how many projects never produce working software at all: the developers write a bunch of code, but it can’t be integrated or packaged into anything that will run on anyone else’s computer. The way to prevent that failure mode is to deploy your software on day one, and keep it deployable as it grows.

What goes into a walking skeleton?

Now I’m going to venture outside the agile software canon and talk about how I personally like to build walking skeletons.

Developer Documentation

My first step is generally to write a README file that tells developers how to obtain a copy of the source code, start working on it, and verify their changes.

(I’m realizing now that I’ve skipped over a technique that’s arguably more foundational than Walking Skeleton: readme-driven development. I guess that will be the next post.)

Since a readme is often addressed to users as well as developers, I usually make a separate “Development” section at the end. Sometimes I even hide it, as I did in the README for my RSS feed generator, marss. Open source projects often have a separate CONTRIBUTING file. You could follow that pattern, too, though IMO it makes the instructions slightly harder to find.

The most important part of the developer readme is a list of the shell commands that all devs will need to run as they work. These commands should be simple: one or two words. They should not require arguments or other customization. This simplicity ensures that everyone working on the software is actually using the same set of tools, not partially-overlapping sets of similar tools. Consistent tools make consistent results.

To run your tools, you can use make, or simple shell scripts (e.g. ./test) or a language-specific task runner like pnpm or rake. Just be consistent.

When tools are simple, documentation can be simple. Here’s an example of the docs I like to write and read:

yarn         # install dependencies; run one-time setup
yarn ts      # typecheck in watch mode
yarn serve   # start dev server
yarn test    # run unit tests (fast)
yarn sys     # run system tests (slow)
yarn lint    # find defects
yarn fix     # fix formatting
yarn verify  # run all checks (do this before you git push)
yarn release # compile, verify, and release a new version

In the spirit of readme-driven development, I usually write the dev docs before I even install anything. The documentation functions as a to-do list of the tools I need to set up. Of course I’ll amend and augment the list later, if I need to.

Tools

After you write the readme, the next natural step might be to start building the tools you just documented. But you’ll quickly find that you need some material to test your tools on: e.g. a unit test that asserts true == true, or some compilable production code. What I generally do is build the “hello world” app and its tools together: a bit of app code, a bit of tooling code, in alternating steps.

As you set up the tools, any configuration files you create should be committed to the source code repository. You might even want to commit editor configuration, though that can get contentious.

Deployable “hello world” program

What exactly does the walking skeleton of a program do? It depends on what it wants to be when it grows up.

If it’s going to be a game: you can pop up a window and paint it black.

If a library:

export function hello() {
  return "Hello, world!"
}

If a client-only web app: display “Hello, world!” on the page using your UI framework of choice.

If a command-line tool: console.log(“Hello, world!”)

If a full-stack app, you’ll need a client, a server, a database, and some dummy data (perhaps inserted via a migration) that the client fetches from the server and displays. Consider the twelve factors. (Yeah, this one is an order of magnitude more work than the others. There’s a reason people like Rails and Phoenix.)

Putting it all together

The overall goal is to end up in a situation where:

• All the tools are built and documented.

• All your verification checks pass.

• You have deployed a “hello world” app to a production-like environment, using the deployment process you documented.

• Your tooling can remain unchanged as source code is added to the project (see: O(1) Build File).

But Ben, this is so much work. Why not just use an off-the-shelf project generator?

So far I’ve been describing this process like you’re going to write every line of code in your walking skeleton from scratch. But there are plenty of project generators (e.g. create-react-app) that will set everything up for you with a single command. Why not just use those?

Well, maybe you should. If you’re on the clock, and you’re using a programming language in which you’ve never built a walking skeleton from scratch, don’t start now. Look for an existing project template and use that. You’ll find out where the rough edges are soon enough. Maybe you’ll improve on it for your next project.

The problem with off-the-shelf templates is that they’re never going to be exactly suited to your needs. They tend to include a lot of stuff, some of which you will use, some of which you won’t, and some of which you will tolerate while wishing it were configured differently. Interactions between tools mean that every tool in the codebase increases the difficulty of adding more. Extra tools are thus a burden you will have to carry for the lifetime of the project. You could try to remove the tools you aren’t using, but it’s harder to rip out stuff you don’t want than to add stuff you do.

So I strongly recommend working your way up to building walking skeletons by hand, professionally. Start with your own personal projects. It’s good practice, and will deepen your familiarity with the programming language and its tooling. Do it six times (another technique I need to write about) and you’ll be an expert. Then you can safely try it at work.

You might well ask, “what’s the point? The off-the-shelf templates are good enough.” But there’s a huge amount of confidence to be gained from knowing the purpose of every single line of code in your project’s infrastructure. Or to put it another way, there’s a huge amount of confidence to be lost when on day one of your project, you’re already responsible for maintaining code you didn’t write and don’t fully understand.

Try both options. I bet you’ll feel the difference.

Further Reading

• Alex Kladov’s “Basic Things”

• Examples of walking skeletons I’ve built recently:

  • Example 1

  • Example 2

Somewhere in between, we have code. There are lots of ways we can structure the code for any given software process. Many, many (infinitely many?) different structures can create identical behavior. Yet the thesis of software design, as a discipline, is that some of these structures are “better” than others, even though behaviorally they are all the same.

This claim seems to take us into the realm of subjective opinions. Who’s to say what’s better? What does “better structure” really mean?

Recall from the previous post that our high-level goal is to make software development less stressful and more joyful for everyone involved. And that a lot of the stress in our line of work is ultimately caused by mental models that don’t match reality. If we could build accurate mental models, software development would be easier and more predictable, and we would suffer fewer mishaps along the way.

As it turns out, the structure of the code can help or hinder our modeling efforts. For the purpose of Process to Processes, “better code” means code that helps us build mental models of the system.1

However, that definition is too abstract to be practical. We need more specifics. It would be nice if we could look at any given chunk of code and say specifically what’s good or bad about it. It would be even nicer if we could turn those evaluations into a to-do list of how to improve the code.

I think we can get there, but it will probably take a book’s worth of text and examples to explain how. In this post, we’ll start our journey with a high level overview.

Introducing CEVICHE

Software people have invented various acronyms to try to characterize what makes code good. We have (at least) SOLID, CUPID, TRUE, and WARMED. Coming up with a coherent acronym seemed like a fun challenge, so I thought I’d try my hand at it. CEVICHE is the (somewhat raw) result. It’s a list of the properties of code that enable developers to build accurate mental models of the system.

Good code is:

• Controllable:

  • You can make the code do what you want.

• Efficient:

  • It doesn’t waste your time.

• Verifiable:

  • It inspires trust (via tests or otherwise).

• Instructive:

  • It might teach you something.

• Consequential:

  • It’s load-bearing.

• Harmonious:

  • It plays well with the rest of the system.

• Extricable:

  • It makes sense in isolation. You can confidently use it, repurpose it, and ultimately delete it.

CEVICHE is meant to complement the other acronyms (SOLID, CUPID, TRUE, WARMED), not to replace them. Comparing and contrasting them is left as an exercise for the reader.

Let’s explore the CEVICHE properties in more detail.

Controllable

Great software is controllable. You can find all the knobs and levers, and you know what’s going to happen when you pull them. Whether you’re changing the code, or using existing code, it’s easy to get the software to do what you want. The result is that controllable code does what its authors intended it to do.

Another C-word that I considered for this spot was correct. This seems like an obvious choice. We all want code to be correct, right?

The question is, though: correct by what standard? Usually, in application development, there is no formal spec for what we’re doing, and even if there is, it will probably change by the next release. This kind of “correctness” isn’t stable; rather, it’s based on the whims of users and product managers. The desired state of the software is…

• a moving target

• not fully knowable (we can’t see inside our users’ heads to know what they want)

Whatever definition of “correct” we set up today is likely to be gone by tomorrow. So instead of asking “is the code correct,” let’s consider a slightly different and more useful question: will it do what we intended?

As David Bryant Copeland writes in “Actual Reasons to Use TDD”:

We can all agree software should do what we expect. Set aside “correctness” (a meaningless term if I’ve ever heard one). Don’t worry about “working software”. Instead think about the question on our minds as we write code, the question we had from our first moment of coding, and that we still ask as we do our jobs today: is the software doing what I expect?

—David Bryant Copeland

If we can keep the software doing what we expect it to do, moment by moment as we program, then we can easily adapt it to whatever definition of “correct” our customers throw at us. In order to do that, we have to control the software and keep it controllable as it grows.

Efficient

I have some qualms about including “efficient” on this list, because programmers are already prone to “optimizing” all the wrong things in all the wrong ways. So remember Donald Knuth’s warning:

Programmers waste enormous amounts of time thinking about, or worrying about, the speed of noncritical parts of their programs, and these attempts at efficiency actually have a strong negative impact when debugging and maintenance are considered. We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil.

Yet we should not pass up our opportunities in that critical 3% [. . .] but only after that code has been identified. It is often a mistake to make a priori judgments about what parts of a program are really critical, since the universal experience of programmers who have been using measurement tools has been that their intuitive guesses fail.

—Donald E. Knuth, “Structured Programming with go to Statements”

In spite of my doubts, I am going to advocate for writing fast programs — for a particular definition of “fast.” My motive is simply that I think many programs today are too slow to support an optimal development process. For instance, the popular JavaScript test framework Jest takes longer to start up than Google Chrome! That’s way too slow to run as part of a programmer’s “inner loop.”

Indeed, speed is one of my most common complaints with modern software, and one of the main factors I consider when making “buy vs. build” decisions. I’ve written a test framework and a static site generator because the alternatives were either too slow or too cumbersome for me to feel really comfortable using them.

This isn’t just my pet peeve. In 1982, two researchers at IBM discovered that shortening computer response times to 0.4 seconds (from the accepted standard of 2 seconds) resulted in a disproportionately large improvement in productivity. When people no longer had to wait for the machine, they typed commands faster and spent much less time collecting their thoughts. The critical threshold of 400 milliseconds has become known as the Doherty threshold, after one of the researchers.

Another important threshold is 80–100 milliseconds, the “threshold of noticeability.” While the Doherty threshold is a good target for “conversational” interactions like command line interfaces and web browsing, response times below 80 milliseconds are required for an interaction to feel immediate, like you’re manipulating a physical object. For instance, clicking a button should give you some kind of feedback within 100 milliseconds — at the very least, an animation confirming the click. Similarly, characters typed in a text field should appear in under 80 milliseconds. It’s pretty inexcusable for something so basic to take longer than that.

If you’re writing a game or an interface that needs to be animated, there’s a third threshold at 16 milliseconds—your budget for rendering one frame.

In light of these thresholds, I can explain what I mean when I say that programs should be “efficient.” An efficient program is one that responds fast enough to support an optimal user experience. That means commands should run and webpages should load in 400 milliseconds, GUIs should give you feedback in 100 milliseconds, and animations should run at 60 frames per second.

How can we hit these thresholds? For the most part, don’t worry about optimizing application code. The performance of a typical application is largely determined by three things (in no particular order):

• Feature complexity. with fewer, simpler features, your code can run faster. Focus on the most valuable features and drop everything else.

• Third-party libraries. The inner loops of your program will probably not be in code you wrote yourself. Choose fast libraries.

• Architecture.

“Architecture” includes stuff like:

• Is your UX event-driven, request-response, or batch?

• What programming language are you using?

• What database are you using? (or: how do you organize data at rest?)

• When and how does I/O happen? Is it parallel or sequential?

• How far does data have to travel over the network?

• Are you making many small web requests or a few large ones?

• Are you using one thread/process, or many? What is your strategy for inter-thread or inter-process communication?

The “fast” answers to these questions are often counterintuitive. For now, the best heuristic I can offer is the KISS principle:

Haskell can be faster than C. Flat files can be faster than a database. Single-threading is often faster than multi-threading unless you’re operating at an astronomical scale. You always want to keep in mind how much data or traffic you really need to handle, and not overbuild. Simple architectures scale farther than you think. Start simple, measure, and optimize the bottlenecks.

Verifiable

Trust, but verify.

—Russian proverb, often quoted by Ronald Reagan

A verifiable program is one that gives us a reason to trust it. When we think of “verification” we often think of “testing,” but the concepts are not synonyms. Software verification includes testing, but also some other techniques:

• Static verification techniques

  • Typechecking

  • Linting

  • Code review

  • Formal proofs

• Dynamic verification techniques

  • Manual testing / QA

  • Unit testing

  • Automated system testing

  • Monitoring

  • Runtime assertions

You don’t need to use all of these techniques for every program. But they are all useful. As always, pick and choose the most valuable techniques for your context.

Together, the production code and the systems that verify it can be considered a self-verifying system. A codebase that contains its own tests, types, linter rules, etc. is self-verifying.

There’s more to verifiability than just putting tests, types, and other checks into a system. The code itself needs to be shaped to make verification easy. In order to be easy to test, code needs to have a simple, consistent interface, a cohesive purpose, deterministic behavior, and, ideally, no effects. There are also constraints on the shapes of code that can be reliably typechecked, as anyone who has tried to retrofit TypeScript onto a legacy JavaScript codebase can attest.

Verifiability and controllability go together. A self-verifying system resists attempts to bungle it up, and is thus easier to control. When controllability degrades, verifiability helps us get back on track, letting us refactor without fear of breaking everything. When the code isn’t doing exactly what we want, we can isolate the problem in a test. That way, we can be sure the problem is fixed and won’t come back.

Yet controllability and verifiability are also somewhat independent. While controllability is about having reliable knobs and levers on our figurative control panel, verifiability is about the gauges and dials. In a self-verifying system, we can get information about the current state and feedback about our actions. A self-verifying system can even teach us how to use it. Don’t know what a line of code does or whether it’s needed? Delete it and see what tests fail. Want to see where a function is called? Comment it out and see what compile errors you get. Trying to figure out how a function handles an edge case? Read the tests (or write a new one). With the right techniques, verifiability can be more than a safety net: it can help us feel happy, capable, and confident at every moment while we’re programming.

Instructive

You know you’re reading good code when you can’t tell what problem it’s solving or how it solves it. Good code makes you feel confused, stupid, and ignorant.

—no one ever

According to Ward Cunningham, “You know you are working on clean code when each routine you read turns out to be pretty much what you expected.” But what if you’re a noob like me and you don’t know what to expect? It would be nice if the code could teach me how it works.

Much of the code I work with is “easy to read” only if I already know what it does and why. But sometimes, I come across unfamiliar code and have an “aha!” moment. The code is so lucid, so clear and simple, that it has communicated something new to me and I now understand both the problem and its solution more clearly.

Dan North says that good code is domain-based: it uses the language and concepts of the business domain. It’s nice when variable and function names are recognizable to a nontechnical team member, but we can go one step further. Ideally, programmers should be able to learn the business domain by reading the code. If we need to write and read separate documentation to learn about the domain, we’ve missed an opportunity for efficiency.

Code can, of course, communicate in technical domains as well as business ones. Great code teaches new programmers old tricks. I’ve mentioned this example before, but I’ll repeat it because I love it so much: this regex for extracting C strings from a file taught me how to think about backslash escape-sequences:

// A string consists of:
// - a double-quote character
// - any number of "units", where a unit is either:
//   - an escape sequence: a backslash followed by any
//     character
//   - a literal character other than a backslash, quote, or
//     newline
// - a closing double-quote.
const cString = /"(\\.|[^\\"\n])*"/

Another example, more recently discovered: an algorithm for detecting whether two 2-D line segments intersect. The details of the code are obscure, but the explanation on Stack Overflow makes the high-level approach delightfully clear.

export const segmentsIntersect = (
    [[a, b], [c, d]]: Segment,
    [[p, q], [r, s]]: Segment,
): boolean => {
    const determinant = (c - a) * (s - q) - (r - p) * (d - b);
    if (determinant === 0) {
        return false;
    } else {
        const lambda = ((s - q) * (r - a) + (p - r) * (s - b))
            / determinant;
        const gamma = ((b - d) * (r - a) + (c - a) * (s - b))
            / determinant;
        return 0 < lambda && lambda < 1 && 0 < gamma && gamma < 1;
    }
};

Is it significant that both of these examples have commentary longer than the code itself? Maybe. I don’t always comment my code, but when I do, I aim for comments like these: paragraphs that give a high-level explanation of what’s going on. In my experience, these comments are the most empowering for future readers, and the most durable. They’re also a lot of fun to write.

Still, if you were to criticize the examples above for being terse to the point of obfuscation, I wouldn’t disagree. Maybe what you should take away from this section is not just “Good code is instructive” but also “Good instruction comes with code examples.”

Consequential

Good code is consequential. That is, it does something. There is a reason for it to exist.

This point may seem too trivial to mention, but I’ve seen and written a lot of dead, tautological, and otherwise useless code in my career. It’s easier to write inconsequential code than you might think.

Inconsequential code can be subtle. For example, in the following Ruby snippet, the check for transactions.empty? is not needed, because transactions.all? returns true when transactions is an empty array.2

if transactions.empty? || transactions.all?(&:complete?)
  # ...
end

Do-nothing checks like this can morph into actual bugs as the code changes. I recently fixed a bug in some web server code that looked very similar to the above. It went something like this (pseudocode):

if count(jobs) is 0 {
  return
}
for each job in jobs {
  job.perform()
}
doNextStep()

You can probably spot the bug: doNextStep was supposed to happen even when there were no jobs, but the early return caused it to be skipped. The fix was simply to delete the unnecessary empty-array check.

The examples above are simple, but in complex codebases, whole sections of logic can “die” (when their outputs are no longer used) and become inconsequential code. These sections of inconsequential code are hard to find, so they’re rarely removed. In a codebase with low verifiability, inconsequential code is a Chesterton’s Fence. It can be hard to tell that the code isn’t actually needed, so deleting it seems risky. The cost of proving the code safe to delete is higher, in the short term, than the cost of keeping it around. So it sticks around.

When inconsequential code piles up, the codebase dies by a thousand cuts. No single bit of derelict code hurts much, but in aggregate they are a huge impediment to change.

Harmonious

Good code harmonizes with:

• Team norms (code style)

• Development tools

• Architecture

Disharmonious code compromises the wholeness or coherence of the system, making it harder to describe and thus harder to reason about.

The idea of harmonizing code with development tools deserves further explanation. There are lots of different tools to read and modify code: editors, scripts, version control systems, etc. Code needs to be designed to work with the tools the team is actually using.

One of the most common tools people use to work with code is text search, or grep. Code should therefore be structured for searchability. That all but rules out dynamic approaches like this:

// Bad example: this code isn't greppable.
Database["create_" + entityName](id, attributes)

If you want to find out where Database.create_user is called, this code makes it really difficult.

Another simple example of harmonizing code with tools, from my essay on Christopher Alexander:

I was once on a team writing C++. We had a coding convention that dictated that all member variables should be prefixed with an underscore, like _someName. I suggested that we drop this rule, since our IDEs highlighted member variables in a unique shade of purple that made them easy to spot even without a special prefix. My teammates objected: some contributors to our open-source codebase might be using editors that didn’t have that feature. The prefix was for them, not for us. What seemed like good fit to me (accommodating our code style to the capabilities of our tools) wasn’t a good fit in the bigger scheme of things.

Harmony is related to the notion of conceptual coherence emphasized by Fred Brooks in The Mythical Man-Month.

I will contend that conceptual integrity is the most important consideration in system design. It is better to have a system omit certain anomalous features and improvements, but to reflect one set of design ideas, than to have one that contains many good but independent and uncoordinated ideas.

—Fred Brooks, The Mythical Man-Month

Conceptual integrity impacts the development process, because when a design choice is at odds with the wholeness of the system, it tends to lock in other choices and make the code more rigid.

A thought experiment: say we have a codebase with features A, B, and C. These features are independent, in the sense that we can understand, test, use, and improve each one in relative isolation from the others. We can also remove any feature if we find it’s no longer valuable.

Now imagine someone wants to add a disharmonious feature, X. Feature X doesn’t slot nicely into the design. Instead, it cuts across the functionality of A, B, and C, requiring them all to change in different ways. So after adding X, we have a system A’, B’, C’, X. Now, awkwardly, none of the features can be understood in isolation. You need to understand X to understand A’, B’, and C’ in their entirety. Moreover, A’, B’, and C’ can no longer be removed, because they are needed to support X.

With only four features, this might be manageable, but of course real systems are more complex. If you start with a dozen or more harmonious features, and then tack on a few disharmonious ones that lock together the others in various combinations, you’re well on your way to spaghetti code.

Unfortunately, I don’t have a real-world example handy, and so this explanation of why disharmonious changes hurt might be totally bogus (though impressionistically, I’m pretty sure I’ve experienced it happening). It’s just my current hypothesis. An area for future research, I suppose.

One way to deal with this situation is simply not to build feature X. But that’s not very satisfying. What if we really need it? Think about what design would accommodate A, B, C, and X easily. Refactor the system to that design first. Then add feature X. Kent Beck said it best:

For each desired change, make the change easy (warning: this may be hard), then make the easy change.

Extricable

One more attribute of great code, and then we’ll wrap up. Great code is extricable from its context. Because it is extricable, it fits in your head, you can understand it in isolation, and you can reuse it in situations its author never imagined.

My first full-time programming gig was working on a Ruby on Rails app for an e-commerce site. One of the nice / scary things about Ruby on Rails is, it makes it really easy to run ad-hoc code in production. You just shell into your server, type rails console, and bam, you’ve got an interactive Ruby interpreter, ready with all your web server code and a connection to your production database. The nice thing about this, compared to running SQL statements directly on your data, is that you have access to all your business logic: validation, after_save hooks, and even whole workflows if you need them. So the risk of getting your data into an inconsistent state is (arguably) less than if you had a SQL prompt.

On one memorable occasion, there was a bug that got a bunch of customer accounts into a weird state, and it was my job to get them unstuck. I knew there was a Ruby method I could call that would do what I wanted; it was called something like finish_signup. There was just one problem: finish_signup would do a bunch of things that I didn’t want, as well as the thing that I did want. E.g. it would re-send the welcome emails that all of those customers had already received.

I eventually got the situation untangled, but it wasn’t as easy I would have liked. And I narrowly avoided substituting one problem for another. finish_signup was a footgun.3

My takeaway from that experience was this guideline: “write code that you’d trust in a production incident.” When you’re dealing with an emergency, you don’t want to have to think about what hidden side effects might be invoked by a piece of code. You want code that’s predictable and side-effect-free.

In the years that followed, I came to appreciate how this guideline fits in with approaches like ports-and-adapters (a.k.a. hexagonal) architecture, “functional core, imperative shell,” and functional programming more generally. When code is made of pure functions and data is immutable, both code and data are easier to move around.

• Data can be sent over the wire or persisted

• Logic can move from the client to the server or vice versa.

• Application code can be reused in development tools, like a making app or database migration script.

• The core of your web app can be extracted to a library and repackaged as a command line tool, desktop app, or mobile app… or simply distributed as a standalone product.4

Mobility of logic and data makes it possible to redesign the architecture of your application — the arrangement of processes and how they communicate, the data storage technology, the web framework you’re using — without making any changes to your business logic code. Likewise, it ensures that changes to business logic don’t cascade into infrastructural code. That’s good, because business and architecture are separate concerns. They change at different rates, at different times, and for different reasons. Having to change one when you change the other makes every change much more expensive.

The property of extricability, though, isn’t just about writing functional code and immutable data, nor about separating business concerns from technical ones. It’s about separation of concerns more generally. Extricable code is meaningful and comprehensible in isolation. You can run it without running the entire system, and you can understand it without knowing how it’s currently used. This property allows you to change code safely, even if you don’t understand every bit of code in the system.

Wrap-up

We all want software development to be more predictable and less stressful. To make it so, we need an accurate mental model of the system. The best way I know of to start building that model is to write code with the CEVICHE properties.

CEVICHE is far from perfect. You’ve probably already thought of things I’ve left out. What are they? Are there any properties you disagree with? Let me know in the comments.

In subsequent posts, we’ll look at specific techniques that help create the CEVICHE properties.

I haven’t worked on my book, Process to Processes, for a couple months. I lost steam because it just felt pointless. I kept asking myself “who is going to pay (in time or dollars) for this? To hear people in the industry talk, most software companies don’t seem to care about making better1 software, so where’s the market?” I’d convinced myself that if value didn’t flow through, end-to-end, from software buyers to sellers to programmers to me, there would be no audience for the book.

And the next thought after that was, “do I really want to help random software companies make more money, given how exploitative most of them are?” The answer is no, I don’t.

I recently realized that this framing is self-defeating and silly. Moreover, it just buys into the capitalist myth that says that money is the be-all and end-all of what we do and how we do it. That’s just not true.

The problem I’m trying to address is not that software companies aren’t making enough money. The problem is…

Software development is stressful!

It’s stressful for everyone involved, in all kinds of ways:

• Managers: The project is late, and QA found 150 bugs in the last build!

• Programmers: The code makes no sense! Tests are failing and you can’t tell why. Your progress is delayed by handoffs, dependencies, clunky tools, and endless meetings.

• Users: The new UI is impossible to navigate! And it’s ugly!

Stress comes from unpleasant surprises. These surprises happen whenever our mental models of the system don’t match reality. The problem is, when mental models and reality fight, reality always wins.

People often react to this by trying harder to control reality. This is the origin of Gantt charts, elaborate design documents, and fear-driven defensive programming. But these techniques just create frustration and busywork — and surprises often continue to happen anyway.

Fortunately, there is a better way. By building more accurate mental models, we can reduce the frequency of surprises, and equip ourselves to deal with the remaining ones in less-stressful ways.2 The techniques in Process to Processes focus on modeling systems and keeping them easy to model as they grow.

Maybe you’re not in the market for stress-reducing techniques. Maybe you’re one of the lucky few. “My job isn’t that bad. I clock in at 9 and clock out at 5. I get my work done. My boss likes me.” That’s great! But you might still be missing out, because…

Software development can be joyful

For me, joy in software development comes from a few different sources:

• seeing my own thoughts reflected back to me

• being the conduit for a smooth flow of information, from intention to action to result to feedback

• mastering a new skill

• giving others the same opportunities for joy.

I’ll never forget the thrill of writing my first program (well, “writing” — my dad helped a lot). All the program did was display a button that printed “It Worked” when you clicked it. But seeing that message appear caused me to literally jump for joy.

There is something incredibly reassuring about explaining your thoughts to a chunk of silicon, and having the chunk of silicon repeat them back to you as objects that change color and move and dance. It makes you feel smart, like you are not deluded, like your thoughts make sense. They must make sense, because you just taught a system made out of math how to think them.

Learning to program is hard. Learning to program professionally is even harder. But once you’ve practiced the relevant skills long enough, software development becomes a virtuosic improvisational performance. It’s almost effortless. Most of the time, you can just go with the flow, responding gracefully to whatever happens.

That sounds nice, but how can we get there? There’s no secret, really: just keep using the techniques for low-stress software development and gradually improving on them day by day. It’s like we’re climbing a mountain: there’s no magic trick that will get us to the top. You climb by taking a step, and then taking another step, over and over.

It works better this way

Some party poopers might find all this talk of joy a bit heretical. They don’t pay us to have fun! But joy in programming is not about goofing off, nor is it some extra, tacked-on activity that costs net time or money. Joyful programming is simply effective programming. We do it because it works. It is more efficient than the alternative.

The kind of people who become programmers and developers have ‘fun’ when the effort they have to put out to do a task challenges them, but is just within their capabilities. ‘Fun’ is therefore a sign of peak efficiency. Painful development environments waste labor and creativity; they extract huge hidden costs in time, money, and opportunity.

If Unix were a failure in every other way, the Unix engineering culture would be worth studying for the ways it keeps the fun in development — because that fun is a sign that it makes developers efficient, effective, and productive.

—Eric S. Raymond, The Art of Unix Programming

That said, getting to a place where joyful efficiency can happen does take some upfront investment — e.g. giving teams space to learn and practice. I’ll talk about strategies for managing that in the book. For now, let me refer you to my thoughts on getting out of the “alignment trap.”

In the next post, I’ll give a high-level overview of the qualities of code that enable low-stress, joyful software development. Stay tuned.

The process of modifying code usually goes like this:

1. Try to make your intended change

2. Discover the structure of the existing code doesn’t accommodate your change very well.

3. <do something about it>

4. Finish making your change

This post is about step 3. What do you do when faced with non-ideal structure?

You have basically three options:

1. Stack. You shelve your work in progress (e.g. using git stash) and focus on improving the structure, as a subgoal of your overall task. We might call this “prefactoring.” Once the structure is right, you return to your original goal.

2. Queue. You add a note to your to-do list, so you’ll remember to come back to the structural problem later. Then you hack in your intended change any old way it will fit. When you’re done with that, you review your to-do list and work on each item in turn until it’s done.

3. Shrug. You hack in your intended change and deploy to production.

Each of these options has pros and cons.

Stack

The nice thing about stacking your work is that when you’re done, you’re done. Once your feature works, there are no loose ends to clean up; you’ve already taken care of that.

Stacking has many downsides, though.

• Deep stacks are scary. Halfway through refactoring, you may discover another subproblem you have to solve… and another, and another. Remembering where you are in the stack takes precious slots in your working memory (of which you have only 7, plus or minus 2). The more slots are taken up by navigation, the fewer you have available to think about the code.

• Interruptions are costly. Once those 7 +/- 2 memory slots are swapped out, restoring them is a difficult, lossy process.

• What’s more, you don’t know how deep the stack is going to grow, so you are constantly making strategic decisions based on incomplete information. At what point do you cut your losses, throw away your work in progress, and try one of the other strategies?

• The tooling support for stacking isn’t great. git stash works about as well as it can, but you still get merge conflicts when you pop a stash, and that feels yucky. You thought you were about to finish a subtask, but now you have a new one: fixing the conflict.

• Finally, there’s a risk that when you’re done prefactoring, the new structure won’t actually accommodate your feature. Your changes are based on some degree of speculation.

For these reasons, I tend to prefer the next strategy, queueing.

Queue

There’s a lot to like about queueing:

• You’re usually taking small steps that are easy to reverse. The code is shippable after every step.

• There’s less risk that you’ll make refactoring changes that aren’t helpful to your overall goal.

• Interruptions aren’t as big of a deal; it’s easier to resume where you left off.

• The tools are ubiquitous; everyone has a favorite to-do list technique.1

Downsides include:

• Sometimes you can’t figure out how to get even a hacky version of your feature working — which is the first step in a queueing approach. You need to improve the structure before you can move forward at all. In these cases, you have to start with a stack, and maybe switch to a queue later.

• There’s a temptation to quit before finishing everything on your to-do list. Heck, there’s a temptation to quit before starting anything on your to-do list. There’s a voice in your head saying “Can you really justify spending time on refactoring? You were able to implement the feature, so the code must be fine! Just ship it!” Because of this, queueing can decay into the third strategy, shrugging. Queueing takes discipline.

These two downsides are, interestingly, two sides of the same coin. Tempting as it is to leave our to-do list undone, that decision will come back to haunt us eventually. Someday, the hack-it-in approach will stop working, and then we’ll have to tackle a deep stack of fixes to make progress. When we have to stack, it’s because those who came before us didn’t queue.

This brings us to the third approach, shrugging.

Shrug

Shrugging is my ad-hoc term for giving up on structure, and just throwing another stick on the dumpster fire of legacy code.

Shrugging often isn’t a deliberate decision. I tend to shrug when I mix the stack and queue approaches in an unstructured way, intending to come back and fix certain things but not writing them down or really committing to them. At some point, my code is working and I can’t remember everything I wanted to fix. Since the fixes don’t feel urgent or important anymore, the temptation to “just ship it” is strong.

Sometimes, though, shrugging is a deliberate decision:

• I don’t know how to improve the code, or don’t feel empowered to do it. Social pressure is a major factor here. I don’t want to mess with the structure of “someone else’s” code.

• I am working within a pull-request workflow, and have to choose between:

  • putting all my changes in one PR, which makes them harder to review and thus lengthens the delay before I can deploy them.

  • splitting my changes up into many refactoring PRs, which makes merging them all a pain. Also, people tend to review the newest PR first (because it’s the one they were last notified about) when I need to merge the oldest one first.

  
  In such cases I sometimes decide that refactoring isn’t worth the effort.
  
  The mitigation for these problems is to pair on refactoring changes. Pair programming has many advantages, but one that I’ve come to appreciate recently is how it makes this dilemma go away. Pairing on a big refactoring expedition is much easier than reviewing the results of one after the fact. Plus, if you pair with the “owner” of the code you’re changing, the social aspects become easier to navigate too.

  Of course, depending on your company’s culture, asking someone to pair can feel socially awkward too. I don’t have a solution for that yet.

Conclusions

The following points are mostly meant as reminders to myself. Your mileage may vary.

• Separate refactoring (structure-only changes) from behavior changes. As in, put them in separate commits.

• In general, prefer queueing to stacking when making a sequence of changes to legacy code. Keep the code shippable at all times.

• Keep a to-do list. It can be very lightweight. Bookmarking annoying code with a TODO comment only takes a second, and searching for those comments in your git diff is similarly easy.

• Prefer pairing to async code review for refactorings.

I spend a lot of time thinking about why there's so much bad code in the world, and what we can do about it. I hypothesize two reasons code quality tends to degrade:

• The costs of poor code quality are hard to see, because of how quality shapes decisions at the organizational level.

• Executives and managers don't have the detailed knowledge they'd need to reap the benefits of good code. A strictly command-and-control organization can't take advantage of code quality; teams and individuals need local agency. Such an organization has little reason to prioritize code quality, and little hope of doing so effectively.

These certainly aren't the only two causes of bad code, but they're the ones I'll focus on in this post.

Hidden Costs

Imagine you have two computers: an old clunker, and a new, top-of-the-line machine. The reason you keep the old computer around is that it runs business-critical software that would be too difficult to port to the new computer. Still, you try to touch it as little as possible, doing most of your work on the new computer.

The old computer is slow and annoying to use. When you're using it, it feels like it's costing you a lot of time. However, when you look objectively at how much time you're actually spending with it, you realize it's not actually that much time, in the scheme of things. You touch the old computer so infrequently that the inefficiencies don't add up to much.

Now, here's the thing: if the old computer were faster and easier to use, you'd use it more. You use it infrequently because it's inefficient. The behavior of the larger system (you plus the two computers) has adjusted to accommodate the relative efficiencies of each subsystem.

Software companies operate similarly. When a part of the codebase gains a reputation for being legacy code, everyone tries to find ways to avoid touching it. Shims are inserted; substitutes are devised. Whenever possible, behavior is implemented somewhere else.

This leads to a vicious cycle: avoidance of legacy code leads to weird architectural decisions in other parts of the codebase, turning them into legacy code too. But the process is gradual. In the meantime, software development can continue, and the company can keep making money.

More perniciously, bad code directs attention and effort away from certain opportunities. If a feature or product doesn't "pencil out" — if the cost of implementing it would be impractically high, due to poor code quality — then it will never get worked on. In this situation, the cost of changing the bad code will never be paid, but the potential value of the feature won't be realized either.

So it's not that poor quality has no cost. The costs are simply invisible, because they show up as a decrease in value rather than an increase in expenses. How do you measure the cost of not working on code, of not building a feature, because it would be too expensive or risky to try? How do you even notice it? The problem is made worse because working in this kind of environment for a long time can cause a kind of learned helplessness, where you don't even see the opportunities that are available to you.

What's a responsible engineer to do in such a situation? Follow the Scouts' rule: no matter what code you're working on, leave it better than you found it. Or at least, don't make it worse. Although remediating the bad code now might not make economic sense, preventing it in the past would have (if only we had a time machine). We can't undo those past decisions, but we can start making better ones.

Unexpected Benefits

A few months ago, Kent Beck wrote an executive summary of his book Tidy First, titled "The Surprise Factory." The idea of the Surprise Factory is that tidy code produces delightful surprises, in the form of unexpected opportunities to add value to the company. (Kent later decided that "surprise" had too many negative connotations, so he changed the name to "The Gift Factory.")

Here's the problem that arises when this theory meets practice: although high code quality does produce opportunities to add value, executives can't see which specific opportunities are present. Code quality is not a scalar value; "good code" cannot make every imaginable change equally easy. Rather, we call code "good" when it can meet the specific demands placed on it. But executives aren't looking at the code, and can't see which specific demands it might be capable of meeting. The opportunities presented by the Surprise Factory are thus invisible to them.

Without a detailed understanding of the code, executives and managers only have a few crude knobs to turn: one knob might be labeled "more ambitious / less ambitious". Another knob might adjust which parts of the codebase or the product receive the most development effort.

The crudeness of these controls all but ensures that code quality will degrade over time. If executives respond to a high-code-quality, high-opportunity environment by simply turning up the "ambition" knob and directing effort toward the highest-quality parts of the codebase, the code will be ruined by developers trying to hit deadlines: it's unlikely that the opportunities coming out of the Surprise Factory will align perfectly with the the plans that trickle down from the executives' vision. But turning the knobs the other way would be folly: you'd burn out your programmers by making them work on the cruftiest code, and you'd have little to show for it in the end.

Again, what's a responsible engineer to do in this situation? I've come to the conclusion that it's my job to reveal value-adding opportunities to my employer, so they can take advantage of the surprise factory. I do this in a few ways:

• I suggest features that I think would be easy and valuable to add.

• When my team is estimating stories, I point out cheaper alternatives to the proposed design.

• I make delivery forecasts based on data, not vibes.

• I cut out low-value work where possible.

One caveat to this recommendation: in order to pull it off, you need design and product skills as well as engineering skills. Nothing's more annoying than a programmer who won't shut up about the weird feature or design idea that they want to shove into the product. However, it seems that the recent trend is for engineers to take on more design and PM responsibilities anyway — gone are the days of PMs writing Gherkin and designers insisting on pixel-perfection. For better or for worse, we programmers have the power now. We should learn to wield it.

I wanted to have one hat rack where I could hang all my internet hats. benchristel.com is the hat rack.

(This idea is analogous to the entrypoint document pattern for software projects, which I need to write a book chapter about someday soon.)

You won’t find much on the site itself, yet, except a big pile of links I’ve bookmarked. But I wanted to let you know about it because it relates to my near-term plans for this newsletter.

In short: I want to be less dependent on Substack. I like publishing on Substack, and I have no plans to stop doing so, but I don’t want it to be the only place where people can find my writing. I’d like to see what I can do with indieweb technologies, and generally get involved with the indieweb scene a bit more, because I think it’s important for information-sharing to be decoupled from surveillance capitalism. So I want to shift my mindset towards treating my book and website as primary, and this newsletter as secondary.

What that means, concretely, is:

• I’ll continue to write chapters of my book, Process to Processes, and cross-post them here.

• I’ll also write standalone essays, which I’ll post on benchristel.com and maybe also cross-post here if they seem germane.1

• Treating benchristel.com as the primary repository of my work will make it easier for me to organize my writing, keep it up to date, and format it exactly how I want (I’m still working on this last part).

Long-time subscribers have seen how good I am at following a plan (i.e. not good). With that in mind… that’s my plan.

If you like the current format of this newsletter, don’t worry. From your perspective, nothing will change.

However, if you’d like to subscribe directly to benchristel.com, in order to get up-to-the-megasecond news about what I’m working on, you can! Just drop the URL, https://benchristel.com, into your favorite RSS reader. And if you have no idea what I’m talking about, you can also subscribe with your email, here.

(If you do happen to have a favorite RSS reader, I’d love to know what it is. Let me know in the comments.)

• I am confused

• The Christopher Alexander Post

• The 15 Properties in Software, Part 1

• The 15 Properties in Software, Part 2

• The 15 Properties in Software, Part 3

• The 15 Properties in Software, Part 4

• Adaptation

I feel pretty silly for not re-reading what Christopher Alexander had to say on the matter, back when I published the question that started this whole series. The question, as I then stated it, was, “why do the same 15 properties of structure that characterize beautiful buildings also appear in healthy software systems?” In this final chapter of my series on Christopher Alexander, I want to analyze his solution to this puzzle.

The question I posed is a special case of a more general one: “what is the relationship between fact and value?” Or in other words, “what is the relationship between what works and what’s good?” This question is an ancient one, but it has only recently become urgent. The modern era has landed us neck-deep in planet-destroying utilitarianism and impractical, cloying style, and we need to find a way out before we alienate ourselves into oblivion.

As I dug into the chapter of The Nature of Order where Alexander presents his solution to this problem, I remembered why it didn’t click for me five years ago, when I first read it. It struck me at first as too vague, too woolly and “spiritual” to be plausible or falsifiable, so I dismissed it and forgot about it. But now, after thinking through many examples in several different domains, Alexander’s solution seems far less mysterious to me, and I find myself agreeing with him, pretty much the whole way through.

I’m mostly going to just roll the tape and let him talk, though I will occasionally pause to interject my own commentary. Here is how he introduces the topic, on page 404 of The Phenomenon of Life.

No building (and no part of any building) has real life unless it is deeply and robustly functional. What I mean by this, is that the beauty and force of any building arises always, and in its entirety, from the deep functional nature of the centers that have been created.

In nature there is essentially nothing that can be identified as a pure ornament without function. Conversely, in nature there is essentially no system that can be identified as functional which is not also beautiful in an ornamental sense. In nature there simply is no division between ornament and function. [. . .]

I shall try to show that the functional behavior of buildings, the human life present in them, like its geometry, can all also be understood in terms of wholeness. That means that emotion, movement, light, comfort, climate, balance of functions, the ability of a room to accommodate the behavior in the room, the engineering structure, the manufacturing — all these practical matters can be understood in terms of centers. [. . .] All of it can and must be understood as something geometric happening in space.

During the early and middle 20th century, the idea of function was for the most part understood in a mechanistic spirit. In trying to work out what a building ought to do, how to analyze its way of working, one had the approach that the building’s functions were to be described by a kind of shopping list of “goals.” These goals were defined by the architect or engineer, then achieved.

There’s a clear parallel to agile software development here: Alexander’s “goals” correspond to our features, user stories, epics, and perhaps KPIs (key performance indicators).

However, there were unsolved puzzles inherent in this idea of needs or goals. Those of us who made lists of functions were aware that these lists were inherently arbitrary (dependent on the architect or client who made them, their forgetfulness, lack of insight, etc.) Where was the real list of needs?

User stories are, of course, only a guess — an approximation of what the user might need, might do, might experience. A software project can deliver everything that was planned, on time and under budget, and still fail because the user stories and UI designs didn’t reflect the real set of needs. There seems to be no way around this. If you try to, say, analyze the requirements more deeply before writing user stories, you get into an infinite regress. How do you know the requirements document is correct?

I remember making a long list of some 390 requirements which were to describe the ways in which [Bay Area Rapid Transit] stations could malfunction. But still, there was an intuitive sense that such a list might be wrong, might be missing items, might be profound or shallow. [. . .] Goals were always arbitrary in some essential way, which could not be mended.

[emphasis added]

Alexander singles out this focus on goals as a cause of the schism between beauty and function in architecture:

There were further difficulties. The list of needs or goals, no matter how carefully stated, could only with difficulty be connected to the physical form of a building. [. . .] When it came to the physical beauty, ornament, gracefulness of appearance, these matters, obviously important, were in a different category.

To continue the software analogy: a list of user needs, on its own, doesn’t tell you how to design your software internally, and it doesn’t even tell you what the UI should look like. Under this paradigm, the form of the thing (both internal and external), and therefore any aesthetic or emotional appeal that it has, has only a tenuous relationship to its function. If form is considered at all, it must be after the functional requirements of the software have already been determined. The form may then succeed or fail on its own merits, but that has nothing, supposedly, to do with its function. In this view, form for form’s sake is mere ornament — something you tack on after the fact, to “make it pretty.”

Yet this is unsatisfying, and in fact unworkable, because the form creates the function of the program. The program cannot function, and in fact cannot exist at all, until there is form. So if we try to separate function and form into distinct “phases” of design, we end up slapping together haphazard forms in the “function” phase, and then trying to patch them up in the “form” phase. The result is a system that neither works well nor feels good.

And we still have the problem that the goals we set upfront weren’t complete or correct to begin with. Sigh.

As unsatisfactory as this is, it’s hard to see how we could do better. Under the current paradigm, it seems impossible to create both beauty and function at a single stroke. I say seems because the problem lies not in our abilities, but in our views: our views about the nature of reality, about what is subjective or objective, about the creative process, and about what it means for a building or software system to “work.”

During the 20th century, the possibility of finding ways of designing or thinking about beauty and function in one breath seemed remote and unattainable. It was not possible, intellectually, because we did not have the right intellectual tools. It was not possible, artistically, because we could not think our way into a unitary frame of mind where the two could be fused, unified, in works of beauty which worked profoundly well. That was the state of architecture, almost without change, throughout the 20th century.

By now you can probably see what Alexander is about to do: he wants to unify beauty and function by finding a way to get rid of the list of “goals,” or at least to treat it with a healthy irreverence. Now let’s see how he does it:

[W]ithin the view of order which I have put forward in this book it is possible, in principle, to unify these two broken halves. It is possible to think of architecture in a single way where beauty and function — both contributing to life — can be understood as a single, unbroken whole.

Function, like wholeness itself, is all based on centers. [. . .] As something lives, acts in the world, interacts with the world, different centers appear and disappear. Some are moving, some are temporary. The flux of these moving, transitory centers, and their appearing and disappearing, is the process we call life.

The process we call “function” is the process by which the static system is — or is not — in harmony with this moving system of centers that we call life. [. . .] As cars cross a bridge, they form centers. Each car in itself is a center; the stream of cars forms centers; a traffic blockage is a center. The road system, which has its own geometric centers, is either harmonious, or not harmonious, with the system of cars that are parked, moving, standing, and so on.

When they are harmonious and co-adapted, we call the system functional.

In other words, there is only one kind of harmonious order, which is characterized by the fifteen properties. When we look at this kind of order “from the outside,” as an observer, we see wholeness, beauty, and good function. When we experience the same kind of order “from the inside,” by actually living in a system with the 15 properties — by actually being one of the dynamic centers that creates the life of the system — then we feel whole, at peace with ourselves, free, alive.

The highest purpose of a building, or a software program, is to strengthen this feeling of life in the people around it. And the way that the building or program creates life is very simple: it does it just though its form, through its geometry. Only its geometry, and nothing else.

This is perhaps easiest to see in software systems. The code of a running software application can be viewed as consisting of nothing but pure, abstract structure, like virtual Tinkertoys. The Church-Turing thesis proves the validity of this view: you can compute anything that can be computed with nothing but an elaborate tree of lambdas. So it is only structure, and the order of the structure — the way it is put together, the way the different parts relate — that determines the behavior, and thus the life, of the whole system.

In the same way, the life of a building comes just from its structure. The placement of the building on the site, its relationship to its neighbors, the proportions of the rooms, their arrangement, the placement of the windows and doors and pathways, the way sunlight falls in the rooms, the furniture, the trim, the way the light interacts with materials and human eyes — it is all structure. As we interact with this structure, we label some of our experiences “functional” and others “aesthetic.” But those are just labels. The fundamental thing is the geometry of the structure, and the interactions it creates. In other words, the fundamental thing is the life of the building.

To see the inadequacy of the “functional” and “aesthetic” labels, consider the life of a living room and the furniture and people in it:

• A living room chair may be comfortable, with cushions and upholstery that are pleasant to sit on. Is this function or aesthetics?

• The seating in a living room might be arranged around a hearth — a strong center — and might form a protective boundary that separates the seating area from the circulation paths at the edge the room. This arrangement is functional (conducive to conversation) but it is also beautiful as pure abstract structure: it makes the room feel cohesive, balanced, and harmonious. So is it functional, or aesthetic?

• The hearth itself can be a beautiful center, but it is also practical: in cold climates it provides needed heat to the house. It also provides a focal point for the room: something for people to gather around, and to look at as they talk. But does that satisfy a functional need? Or an aesthetic one?

• All of these properties of the room encourage people to pause there, to sit down, to relax and talk and generally be convivial. Is this function or aesthetics?

These questions don’t have clear answers, but fortunately, under Alexander’s paradigm, they don’t need to be asked. “Function” and “aesthetics” are concepts we’ve imposed on a universe that simply doesn’t care to distinguish between them. Since we made them up, we are free to get rid of them.

To be sure, there are some aspects of life that seem almost purely aesthetic, or almost purely functional. The distinction exists in our modern culture for a reason. But in a paradigm that does away with the distinction, we can still recognize these different aspects of life while also seeing that they are both life, and that they both arise from the same structural properties of centers.

When you view the world from this perspective, everything snaps into focus. Beauty and function are not separate. They are simply two ways of describing a spectrum of experience. That experience is determined by the structure of the system, because everything is determined by the structure of the system.

The functional behavior of each living room is almost geometrical in nature. What makes the room work is the geometrical intensity, vibrancy, of its living centers, their degree of life. The fifteen properties, the field of centers, and the wholeness not only control the way that beautiful buildings look. They thoroughly and completely determine the way that buildings work.

Altogether I believe the functional life of buildings is created by the same field effect among centers which creates the field of centers in an ornament. Each functional “problem” is solved by the cooperation or integration of centers which arise within the building dynamically, while it is working. The field of centers supports not only everything we commonly call ornament in a building but also everything we commonly call function. [. . .] What we call ornament and what we call function are simply two versions of one more general phenomenon.

—The Phenomenon of Life, p. 415

Equipped with this view, the designer, instead of having to grapple with two questions — “how do we make it work” and “how do we make it beautiful” — only needs to consider one: “what should my next change to the form be, to create the greatest feeling of life in the whole?” This is a difficult question to answer, but, as I will attempt to show in my book, not as difficult as it seems. And it is far more workable, practically, than the alternative under which we are currently suffering.

So, to answer my original question:

Why do the same 15 properties of structure that characterize beautiful buildings also appear in healthy software systems?

I think Alexander would say that the 15 properties describe a certain kind of structure: orderly, harmonious, whole — whatever you want to call it. A kind of structure that makes sense. Sometimes we call this sense-making “beauty” and sometime we call it “function” and sometimes we call it “health” or “wholeness” or “life.” It is all the same thing, the same kind of order.

And to answer Alexander’s rhetorical question,

Where was the real list of needs?

I would say that there is only one real need, from which all the other specific needs derive: the life of the whole.

This is the need that I constantly return to when creating software. Whenever I am thinking about what to do and how to do it, I always evaluate the result (or my guess at what the result will be) by the life that it creates. By which I mean: is the resulting interaction more pleasant than the status quo? Or, more profoundly: does it make me feel more alive, more of a person, more connected to the work, more truly at ease being myself?

What is involved in this approach is that we pay attention not only to the functions themselves, but also (and rather) to the overall life of the system as a whole. The approach treats the space as a whole, and tries to make it more harmonious, more alive, more unified as a whole.

—The Phenomenon of Life, p. 419

As strange as it sounds, designing for life works. Here is Alexander’s account of how he designed housing in Peru in 1969, beginning with a home-stay with a Peruvian family:

Before going to Lima, we read various anthropologists’ reports about Peruvian society. It all seemed very exotic, but none of it seemed even remotely useful when we were living in our Peruvian families. For instance, ethnographic reports claimed that Peruvians kept the windows closed at night, even in hot weather, because they didn’t want ghosts to come through the windows with the night air. I never heard anyone say anything like this while I was living in the district of Victoria in Lima.

I found that I could imagine the Peruvians’ feelings best just by being one of them. For instance it was a dangerous place, and it wasn’t safe to leave windows open at night. That was really all the explanation one needed for why the windows had to be closed, even when it was sweltering hot. I found that if I looked at life from the point of view of being one of them, my own feelings, and my own knowledge of what had to be, was more reliable than anything else as an indicator of what was needed for a Peruvian family.

The comedor (dining room) in the middle of the house, where everyone came by, watched TV, or sat and talked on the way in or out, was a wonderful place. Being a member of that family, I knew that I needed and wanted such a room — and I could feel exactly where it needed to be in the house (in the middle of everything). [. . .] I, myself (as Chris Alexander) didn’t have a house like that, and I don’t want a house like that — because for me, in Berkeley, with my family, it would not have made sense — it would not have been part of things, or part of the way my life works. But as a member of that Peruvian family, in the Peruvian culture, in the context of that family which I was a part of, it did make sense. It was natural, necessary, and I could feel its necessity, as part of me.

—The Process of Creating Life, pp. 350–51

By Alexander’s account, the process succeeded:

[P]eople in Peru said that our pattern language and our houses we designed from the pattern language were a more accurate reflection of Peruvian reality than even the Peruvian architects had managed.

People wondered how we did it. But it was really very simple [. . . .] We identified the centers by getting so deeply into the situation that we could feel, in our own bodies, just which ones needed to be there.

The essential technique in the observation of centers, in any social situation, and in any culture, is to allow the feelings to generate themselves, inside you. You have to say, “What would I do if I were one of the people living here, what would it be like for me?” thus inserting yourself into the situation, and then using your own common sense and feelings as a measuring instrument.

Of course you must always check with people, explicitly. You cannot assume you are right. You have to check. On the other hand, checking doesn’t mean just do what people say; their own sense of what is involved can also be in error. One must always go to the root, asking what is likely to create the most life, and maintaining a cautious skepticism, even while pursuing these difficult and soul-searching questions.

—The Process of Creating Life, p. 352

The process Alexander is describing here — and this is in 1969, remember — foreshadows Extreme Programming, which recommends having an onsite customer for the software you’re building. The idea behind the onsite customer is that if programmers live side-by-side with one of their users, day in and day out, seeing how they work, and experiencing their joys and frustrations, they will develop empathy for those users. Empathy makes it much more likely that the team will build a great product. This technique of “feeling into” another person’s experience, by almost literally standing in their shoes, is exactly the same as what Alexander did in Lima.

Christopher Alexander’s philosophy may seem pretty “out there” at first glance, but putting it into practice feels rather ordinary and commonsense. In a way, what I’ve written above isn’t all that far-fetched, compared to the way we routinely do things in software development today. Ideas like service design, incremental development, refactoring, user interviews, recognition of the aesthetic-usability effect — these are the state of the art in at least some software companies. I sometimes feel that we are close to achieving Alexander’s vision, and that the philosophy I’m describing is a short step away from how (good) modern software development currently works.

But we are not close. Though some of us may be heading in the right direction, there is a deep chasm between how we feel about our work today, and how we need to feel, in order to generate the kind of world that Alexander envisioned. I said we are one step away, but in reality that step would be a leap: a quantum leap, into a new paradigm, and an entirely new way of viewing our relationship with the world. We aren’t prepared to make that leap yet.

I remain hopeful, though, that someday soon, we will be.

.

.

.

THE END of the Christopher Alexander series.

What would be required for us to cross the chasm into the Alexandrian paradigm, in which fact and value are unified? I hope to explore that topic in a future post. For now, here is a sneak peek:

Okay, that’s all for now, folks! Back to book-writing for me. And, uh, all my other projects. I have a lot of irons in the fire right now. I hope to have things in a shape where I can share some of what I’m doing with you next week.

Thanks for being here.

Subscribe now