The Problem Statement

The simplest way to visualise reactivity, in my opinion, is as a spreadsheet. You have a series of input cells, containing your initial data, and a series of output cells containing the final results. In between are many more cells containing intermediate computations that need to be done to figure out the final results.

When one of the input cells changes, all the cells that depend on it need to react to that change — the aforementioned reactivity. In practice, though, this is the bare minimum requirement. When building reactive systems, there are usually some additional requirements we impose that make the problem harder:

1. Each cell is recalculated at most once. We don’t do any calculations that are immediately discarded. (“Efficient”)
2. We only update cells that actually need to be updated. Any cells that aren’t affected by the input are left untouched. (“Fine-grained”)
3. Whenever cells change, all the cells change at the same time. There’s never a moment when an intermediate computed value has updated, but the output cell is still showing a result based on the previous input. (“Glitchless”)
4. Each time a node is updated, it may dynamically add or remove dependencies (“Dynamic”)

The first two requirements (“Efficient” and “Fine-grained”) are important for performance. Imagine a large spreadsheet with millions of cells containing formulas — it would be a huge waste of resources to recalculate every single cell, every time any input changes. Similarly, you don’t want to calculate the value of a cell multiple times if you can help it. In general, we want to do the minimum amount of work possible.

The third requirement (“Glitchless”) is important for correctness. We don’t want intermediate states to be observable — if this were possible, then we can end up with invalid states. Consider two neighbouring cells, one that contains a country’s ISO country code (UK, DE, BE, etc), and another that contains the full name of that country. We don’t want to be able to observe the state where the two cells are out-of-sync with each other.

The fourth requirement (“Dynamic”) ensures that we only create dependencies when they are actually needed. This is easiest to see with conditional formulas, so something like IF(<condition>, slow_calculation(B1)). If the condition is true, this formula returns the value of (and therefore depends on) the cell B1. But if the condition is false, the formula returns nothing — and if B1 changes, this cell should not be updated. This is a dynamic dependency — the dependency only exists if <condition> is true.

These requirements will hopefully become more clear as we start trying out different algorithms, and seeing examples of their successes and failure modes. Before we get too deep in the weeds, though, I want to emphasise that not all reactive systems are the same, and some don’t need all of these requirements. For example, lots of simple reactive systems work just fine with static dependencies only, trading off some efficiency wins for implementation simplicity. Similarly, glitches are only important if they are actually observed, so some reactive systems will be glitch-y by default, but provide tools for syncing nodes together if the user actually needs them to be in sync.

But for the sake of this article, let’s assume we need all these things and look at some approaches to implementing reactivity.

Push-Based Reactivity

In push-based reactivity, when a node updates, it notifies (and updates) all of its dependents. We can visualise this as the update being pushed down the chain of dependencies, until it reaches the final node to be updated.

This is a simple, and therefore very common approach. Generally, most event systems, streams, and observables follow this rough pattern. Even promises/futures/async/await can be thought of as a one-time-only push-based reactive tree — each .then/.map/await call creates a listener to the previous step, and then when the initial promise resolves, the update is pushed through the rest of the system.

The single biggest advantage of push-based reactivity is that it is fine-grained. Each time an input changes, we only notify those dependencies that will actually need to be updated. Every other node in the system can remain in a state of blissful ignorance. This is great if we’ve got a lot of inputs that update independently from each other — our spreadsheet is a good example here, as are most GUIs.

However, push-based systems typically are not particularly efficient, and it’s only with additional work that we can fix that. Let’s look at an example of a graph that creates unnecessary work.

According to our push-based system, we update the first node in our graph (A). This pushes a signal to (A)’s dependents that they should now update. In this case, both (B) and (C) update. However, (B) depends on both (A) and (C), so when (C) updates, (B) needs to update again, and we discard any previous work we’ve done there. Similarly, based on just a single update to (A), (D) will receive three different signals to update.

We can improve this somewhat if we make sure we always perform updates in a particular order. Consider a different approach to the same graph above:

1. We update (A), and push a signal to (B) and (C) to update.
2. (B) delays updating for now, knowing there are other dependencies to update first. Meanwhile, (C) updates, and pushes a signal on to (B) and (D).
3. (B) now updates, as both (A) and (C) are now ready. Once finished, it pushes a signal on to (D).
4. (D) updates last of all.

In this version, each node only updates once. We could do this, because we could see the entire dependency graph, and calculate the optimum route¹ through it. If we know the entire graph, we can always calculate the optimum route, but it’s not always a given that we will know the entire graph.

Part of the value of push-based systems is that each node only needs to keep track of its own dependencies and dependents, which makes analysing each node locally easy, but analysing the system as a whole hard. In the extreme case, you might dynamically create and destroy nodes in the tree depending on previous values — this doesn’t make sense for our spreadsheet analogy, but is essentially what’s happening with RxJS’s switchMap operator. Essentially, the more dynamism we want in our system, the harder it is to achieve efficient updates, and the more we want efficient updates, the more we need to specify our dependency graphs up-front.

The other challenge for push-based reactivity is glitches. As I mentioned earlier, glitches are when we can observe two nodes being out of sync with each other. In push-based reactivity, this is very easy to achieve — any code that runs after the first node has been updated, but before the final node has been updated has the opportunity to “see” glitches.

We can avoid this in two ways. Firstly, we can declare that any code that observes two nodes must depend on those nodes, and then apply the topological sort we described earlier. Alternatively, we can declare that any code that might be able to observe two nodes can only be run after all nodes have finished running². These both work, but again they require us to be able to observe the full dependency tree and topologically sort all nodes.

The other problem is that in practice, it’s surprisingly easy to write code that implicitly observes some state without having the proper dependencies, at which point glitches appear again. There’s typically no easy way to fully prevent these cases from cropping up, so some amount of vigilance is required to make sure everything is working.

Pull-Based Reactivity

If what we’ve described above is push-based reactivity, we can draw a diagram of everything happening in reverse and call it pull-based reactivity. But that doesn’t necessarily give us an intuition for what pull-based reactivity actually is.

In push-based reactivity, once a node has finished updating, it calls its dependents. In pull-based reactivity, therefore, we would expect each node to call its dependencies. And because you need your dependencies to update before you can update, we can see how this works: each node updates all of its dependencies, and then updates its own value.

In essence, pull-based reactivity is basically just a stack of function calls. I call a function, and it calls more functions if it needs to, then it returns a result. I can nest these functions recursively as much as I need, and the dependencies will all automatically be calculated for me.

This isn’t quite reactive yet though. We still need some way of triggering the functions to be re-run when state changes.

The easiest possible system is that we just re-run everything. Going back to our spreadsheet, every time we update a cell, we go through every cell in the sheet and calculate its value fresh. When a cell references another cell (e.g. =B8), we first calculate the value of the dependency, then carry on calculating the initial cell’s value. Eventually, we will recursively have updated every cell in the sheet.

You may be able to see some problems with this system, but let’s put those to one side for now, and look at why we might want this kind of system.

The first benefit is that it’s a lot easier to make our code glitchless. Every time we change the input, we make one recursive pass over all nodes, updating them to their new values. As long as we don’t change the input during that pass, all of the nodes will see inputs that are consistent with each other. In single-threaded runtimes like JavaScript, this condition is very easy to achieve, and even if we introduce concurrency, we only need simple locking primitives to ensure that we wait until the pass is finished before making changes to the inputs.

The second benefit is that we get dynamic dependencies for free. If pull-based reactivity is just a call stack, then it’s very easy to conditionally call (i.e. conditionally depend on) some input. We don’t need to maintain an internal list of which dependencies a node is subscribed to or vice versa, we just fetch values as needed.

But there are problems — in fact, there are two big ones that mean this approach tends to work best in very specific circumstances.

The first problem is wasted work again. If cell A1 references B8, and cell A2 also references B8, then when we update all the cells, we still only want to evaluate B8 once, and then reference it in both A1 and A2. We can do this through caching — whenever we calculate a cell’s value, we store it somewhere, and then all future cell references can used the stored value instead of recalculating.

I’m not going to go into the depths of caching in pull-based reactivity, but as the famous aphorism reminds us, one of the hardest things in computer science is cache invalidation. And typically, the more efficient a cache is at reducing work, the harder cache invalidation becomes. So an easy approach might be generation counters, where every time we change any input, all cached values are invalidated immediately, and a harder approach might be an LRU cache of all a node’s dependencies where we need to consider how many entries to cache, and how to determine equality³.

However, there is a second problem to deal with. Right now, we don’t know which cells are actually going to change, so we’re updating all of them. The actual pull-reactivity diagram probably looks something more like this:

Ideally, we’d only update the cells that change, and leave the rest alone. Unfortunately, this turns out to be surprisingly hard.

We can change the problem a bit. React, for example, uses a pull-based reactivity system, but can isolate certain components in the rendered tree and say “only this component and all its children should update”. This means that instead of having to re-render the entire world, it only needs to re-render a given component and its children. The mechanism by which this works is interesting, but I’ll explore that in a follow-up post because this one is already getting too long!

In general, though, we can’t solve this problem with pull-only reactivity. The input node that gets updated just doesn’t have the information to tell us what its dependants are, and therefore what output nodes are eventually going to need to change. But we could try a different approach, where we do try and store that information. A combination of pushing and pulling — some kind of suicide squad push-pull reactivity?

Push-Pull Reactivity

Push-pull reactivity is so named because it does both things: first we push, and then we pull. However, rather than doing the same thing twice, our push and our pull will have different purposes.

Let’s start with pushing. Consider a tree of nodes. If we update one of the input nodes, our goal now is to find out which child (and output) nodes need to be updated. We’re not actually going to do the updating, we’re just going to find out which ones need updating.

We can do this by adding a boolean dirty flag to each node. If it’s set to true, then this is a node that needs to be recalculated. Otherwise, it’s up-to-date. Let’s start with these flags all set to false — we have an up-to-date tree. Now, when we update the input node, we can iterate over all the children of that node, and follow a simple algorithm:

1. If the current node is already marked dirty, we don’t need to do anything and can skip it.
2. We mark the current node as dirty.
3. If the node is an output node, we add it to a list of outputs that need to be updated⁴.
4. Otherwise, we recursively visit all the children of the current node and apply this same algorithm to them.

Eventually, we’ll have a tree with mixed dirty and clean nodes, where only the dirty nodes need updating. Importantly, unlike the original push-based reactivity, the order that we visit the nodes isn’t important⁵. This means we don’t need to figure out the optimal path through the entire tree, and can use a simpler recursive algorithm, as long as we make sure to skip any nodes that were already marked as dirty.

Now let’s try pulling. Last time, one of the issues with pull-based reactivity was that we didn’t know which nodes needed to be updated. But now we do know that — any dirty output node needs to be updated. We even made a list of these nodes while we were marking the nodes as dirty!

So now, for every one of those output nodes, we do the same thing we were doing in the pull step. But we add a couple of additional checks to our logic:

• If the node we’re looking at is clean, we return the value of that node. We know that the existing value doesn’t need to be recalculated because it’s not been marked as dirty, so it’s not downstream of any changed inputs.
• If the node we’re looking at is dirty, we calculate the result, mark the node as clean, and store the calculated result alongside the node.

Once we’ve finished our push and our pull processes, we’ll end up with an all-clean tree of nodes, and we’ll have updated all of our output nodes.

Let’s look at our requirements again, and see how well push-pull reactivity does.

• Efficiency: When we push, we only visit each node once. When we pull, we again only visit each node once. This is about as efficient as things can get.
• Fine-grained: When we push, we make a list of exactly the nodes that need to be updated. When we pull, we only recalculate those nodes and leave all the others alone.
• Glitchless: Because the recalculation happens during the pull step, we share the same benefits of pull-based reactivity here, which means that if we can guarantee that we don’t change any input during the pull step, then the calculation must be glitchless.
• Dynamic: Pulling is always dynamic, as we discussed before. But because we don’t need any global ordering of nodes, it’s very easy to have a dynamic push step as well, as each node only needs to keep a list of its upstream and downstream immediate neighbours. This structure is typically much easier to manipulate than maintaining a globally ordered list (and a lot cheaper than performing a fresh topological sort every time we want to evaluate nodes).

Nice!

Conclusion

These are the three broad categories of reactivity system that I’m familiar with — ones where a node gets updated by a signal from above, ones where a node gets updated on demand from below, and hybrid approaches⁶.

For the purposes I use reactivity⁷, push-pull reactivity is a really nice tool. The O(n) nature makes it remain fairly efficient as the size of the application grows (especially bearing in mind that the ’n’ there is the number of nodes that need to be updated, which is likely to be a small subset of the total nodes in the system). It’s also very easy to understand what’s happening.

That said, it’s also got its issues. For example, an assumption throughout this post is that it’s possible to do the entire “pull” logic in a single tick, between updates to the input nodes. If that isn’t possible, you might need to convert a long-running operation into a state machine that gets updated in the background, but this can become complicated in general⁸.

Throughout writing this, I ended up in all sorts of tangents that I’ve ended up deleting because they made everything too long and convoluted — I will try and put some of these tangents in a future follow-up post, because I think they’re interesting.

Here, I wanted to add a couple of additional thoughts based on some of the discussions and things I’ve read since writing that post.

Firstly, undo/redo isn’t the only use for the command pattern! This is something I wish I’d made more explicit in that post. Perhaps a more general way of seeing commands is “functions with metadata in a consistent shape”. In our case, the metadata was the undo function, i.e. the inverse function to our original function. But you could do all sorts of other things as well:

• User-readable data, such as the name of the command and a description of what it’s done. We use this in our undo/redo system to show a timeline of actions that the user has taken in the UI, so that they can jump back and forth, and quickly undo chunks of work.
• Parameters for a rate-limiting algorithm. Say you’ve got a handful of routes that need to be rate-limited, but at different rates — you can define each route as a command object with details about how often it can be called, and then provide a generic route handler that finds the correct command, applies the correct limits, and calls it or returns an error as needed.
• Metadata about the function’s arguments. In another place in our application, we have a bunch of built-in functions that the user can call. Each function declares what parameters it takes, which means we can programmatically create a UI where the user can configure the functions.

Secondly, I think it’s really important to see examples of patterns being used in practice. When I was researching about the command pattern, there were lots of articles that described the pattern in very abstract terms, or with a bunch of class diagrams for an OO-style implementation. Of course, design patterns are always going to be somewhat abstract¹ but it can be difficult to get a sense of why you’d use a particular pattern without already having seen it in practice.

In the comments on Lobste.rs, someone posted a link to Game Programming Patterns, and their treatment of the command pattern. This is a fantastic resource, and they do a great job of starting with a real problem and explaining how the pattern helps.

A while back, I saw someone ask whether there was a test suite for design patterns — some set of tests that you could apply to a class to test whether it successfully implemented the builder pattern, or the command pattern, or whatever else. I wonder if this kind of approach comes from seeing too many descriptions of design patterns as UML diagrams only, and not as abstract ideas that can be implemented in all sorts of different ways, be that as functions, or as objects, or as closures, or whatever else.

One final thought: are objects themselves just another design pattern? Consider the core idea of encapsulation: some type t that is bundled together with a bunch of methods of the form fn(t, ...args) -> result. How many different ways are there of implementing this in different languages that all behave roughly the same? I can think of classes, closures, ml modules, abstract data types, and probably more if you pushed me. They might look different, and have different subtleties to understand, but they feel like different implementations of the same underlying pattern.

Why

This is a performance¹ thing. In the project where I was exploring this, we had a large amount of objects representing configuration values. The possible configuration keys were the same, but different objects had different keys set. This approach was causing some issues:

• Serialization and deserialization produced very large strings because of all the repeated keys.
• Comparison/equality of objects was costly because of the number of keys.
• We needed to do a lot of operations like “find the subset of keys and values that are identical between all of these objects”. This was slow.
• We often needed to update subsets of the items by adding, updating, or removing keys, so each object needed to be an independent clone.

Originally, I planned on doing some sort of object interning to reduce the number of objects we needed to keep in memory at any one time. We would keep only one copy of each unique configuration item, and just reference it in multiple locations. The (now dead) Records and Tuples proposal would have been really useful here, and its replacement, Composites looks like it might help but I didn’t want to tie myself to an incomplete early-stage proposal. So if I went down this route, I’d be building something myself.

While looking all this up, I found Justin Fagnani’s article Composite Map Keys in JavaScript with Bitsets, which is mostly unrelated to what I’m doing here, but did make me think of using bigints in the first place.

How

The basic idea is:

1. Define a bunch of fields, how they should be interpreted, their size, etc. E.g. {name: "size", kind: "uint", bits: 8} to represent a number stored as a u8. You also need to know the offset of each field, this can be calculated from the index of each field and the number of bits in the preceding fields.
2. Add functions getBits(bigint, offset, bits) which does bitshifting to fetch the relevant bits from the bigint backing store, and setBits(bigint, offset, bits, value) which does the opposite
3. For each field, add getters and setters that do the type conversions from e.g. JS number to u8.

Honestly, I was impressed by how well Claude Sonnet handled this stuff. It didn’t produce the tidiest code, nor did it find the clearest ways of doing many things, but the basic bit-bashing was largely correct, and I wrote a lot of tests to confirm that it was working in the way I wanted.

In this use-case, not all keys are present at all times. To handle this, I added an extra store present alongside the bigint backing store that was a simple bitfield where if bit i was 1 in the present store, then the ith field had been set in the main backing store. Deleting a field meant simply clearing the ith bit.

Benefits

• The memory usage of the object is about as compact as it’s possible to be. Booleans take up a single bit, colours can be stored as u32 values (for rgba), fields that were previously string enums are now just a couple of bits wide, etc.
• Deserialization is very quick (basically just BigInt("0x" + value) to convert a hexadecimal string back into our backing store). Serialization is slightly slower because I wanted to ensure that unset fields were zeroed-out first, to ensure consistent representations. The resulting string is pretty compact.
• Lots of operations can take advantage of the present bits to optimise what they’re doing. For example, when checking equality, we can first check that the two present bits are equal to make sure that the same fields are set in both cases. When finding the intersection of two values, we can first AND the present bits together, and check only the fields that are set in both values.

This whole thing is surprisingly usable.

Drawbacks

• Fields need to have a max width. For example, you can’t store an arbitrary string in the bigint, because you don’t know when it will end. If you need dynamically-sized data, then this isn’t going to work.
• Bit operations on bigints is slow. I mean, all things are relative, but in general, gets and sets will be faster with plain old JS objects. HOWEVER: if you have a lot of smaller fields, you can cheat a bit and use a number backing store, or use a combination of a number store for smaller fields and a bigint store for larger fields. Bit operations on number objects are very fast, and in my tests, gets and sets were roughly the same speed as getting/setting regular JS object fields.
• The code is going to be way more complex. Expect to write a whole bunch of tests that basic things like getting and setting a property work. I suspect a good library or layer of abstraction could help here, but, having only done this the once, I don’t know what that abstraction would look like yet.

This might not sound like a lot of drawbacks, but they’re all very significant compared to the more niche benefits of this approach. I wouldn’t recommend doing this in most cases.

Is It Worth It?

I’m not entirely sure yet. This is a bit of an experimental side project at the moment, just playing around with one way of optimising one component of the main project I’m working on. I need to see how it feels to use this approach in practice. The goal is not necessarily that bigints by themselves will make things better, but that they’ll enable other optimisations by having much quicker equality checking, etc, so I need to try out those other optimisations and see the results. If you’re reading this in a few months and still curious, reach out to me on Bluesky or something and ask me how it’s going, and then I can update this blog post with the results.

Consider a complicated expression with multiple sub-expressions. This expression is going to be difficult for the next person reading this code to decipher; we should make it easier for them.

There are a couple of ways to solve this. We could break down the expression into sub-expressions, and assign those sub-expressions to intermediate variables. Or we could pull the expression out into its own dedicated function. In each case, the goal is to give either part or all of the expression a dedicated name. This name helps the next reader to understand the purpose or meaning of the expression.

Unfortunately, names are hard. A good, meaningful name puts the next reader in exactly the right frame of mind to understand what is going on. A bad name can confuse the next reader and make the code less legible than before. And finding the right name is a difficult task. It can’t be too long and unwieldy — being too verbose makes it hard to communicate effectively, as anyone who’s worked with German bureaucracy can tell you. On the other hand, it can’t be too short or generic — naming everything x or var will rarely help future readers.

Sometimes, though, I can’t find a good, obvious name. In these cases, rather than trying to force one, I instead write a comment. A comment gives you more space to work with, which means it can be much more exact and precise than a single name. You can use a comment to remove potential ambiguities that a more generic name might have. A comment also allows you the chance to provide more “why”-type explanation rather than just describing the “what”.

A good name is normally far better than a comment, but good names are hard to come by. If you’re struggling to find the right name for a particular chunk of code, consider whether the context would be better explained as a comment.¹

If you’re in that boat, then here is the answer in tabular form:

In this post, I’ll unpack this table and explain what it means in a bit more detail.

What are side effects?

Side effects in this context is code that:

• interacts with the page (i.e. isn’t deriving new values from existing inputs)
• isn’t handled by the framework itself (e.g. adding onClick handlers to a button via JSX, or using async/suspense).

So for the purposes of this blog post, something like this might be a side effect:

// attach a global event listener from
// inside a particular component
document.addEventHandler("keydown", () => { /* ... */ });

But these probably aren’t side effects:

// derive the `fullName()` signal by
// combining a `firstName()` and `lastName()`
const fullName = () => firstName() + " " + lastName();

// attach an event listener to a particular
// element using JSX
<input onKeyDown={() => { /* ... */ }} />

// this does have side effects, but for the purposes of
// this post, those side effects are handled by SolidJS
const [resource] = createResource(() => fetch(/* ... */));

Are my side effects reactive?

There are broadly two types of side effect:

• Side effects that run once over a component’s entire lifecycle — i.e. some code that should run once when each instance of the component is first rendered, and then cleaned up when the component is unmounted, but never between. These side effects are not reactive.
• Side effects that run multiple times whenever an input changes — i.e. code that will regularly be rerun during the lifetime of the component².

For example, the global keydown handler from before will probably only need to run once: we set the handler when the component is mounted, and then remove it when we’re ready to clean the component up. However, the classic useInterval hook needs to use reactive side-effects: whenever the input parameters change, we need to clean up the old setInterval handler and create a new one.

When should my side effects run?

SolidJS’s side effects can be triggered at two different times:

• Immediately, as the component is being created
• Later, once the component has been mounted to the DOM and is ready to be used

Some things only make sense once the component has been mounted: any code that needs to access ref, for example, should run after the element has been created and attached to the DOM³.

Some things are not so clear-cut though. For example setInterval doesn’t require any access to the DOM or to any particular elements, so it might make sense to put it in the “run immediately” category. In practice, however, setInterval should normally only run once the component has been mounted. Why?

The answer is server-side rendering. When a component is rendered server-side, the DOM is never mounted per-se, so side effects that run only once mounted are never run. However side effects that run immediately are run, because they will probably affect how the component will be rendered. In fact, that’s normally the point of having them run immediately in the first place, so they can affect rendering!

If we put setInterval in the “run immediately” category, then it will be run on the server. But the render code will never wait for the interval handler to actually start, it’ll just carry on generating HTML and sending it to the client. And once the HTML has been generated, the component will be unmounted, the setInterval handler will be cleared, and the code in it probably won’t have even had the chance to run once, let alone affect how the code gets rendered⁴.

This won’t break anything (as long as the interval is correctly cleared), but it is a useless call to setInterval, and a useless resource that needs to be allocated and cleaned up at some point. Therefore, if you’ve got a side effect and you’re sure it won’t affect rendering, consider running it only once the DOM has been mounted.

Bringing it together as a table

If we combine the two questions above, we end up with four different cases, as shown in the table I showed earlier:

To finish up, let’s look at those four cases individually.

• createEffect: The first run always happens after the component is mounted. After that, if a signal used in the body of the effect changes, the effect will be rerun. If no signals are used in the body, then this behaves the same as onMount.
• onMount: As the name says, this also happens after the component is mounted, but it is not reactive. This is good for side effects that only need to run once that use the DOM.
• createRenderEffect: Reactively, this behaves the same as createEffect, but the first run will happen immediately (i.e. synchronously before the createRenderEffect is completed). Similarly to createEffect, if no signals are used in the body of the effect, then this behaves the same as running the code in the body of the component.
• no function needed: Remember that the body of your component will only get called once during the component’s lifetime, so non-reactive side-effects that need to run immediately (such as instantiating a third-party library, or using createUniqueId) can be called as part of that body.

Addendum: onCleanup

A lot of side effects require some sort of cleanup to happen later — for example, starting a setInterval timer requires cleaning up that timer when it’s no longer needed. For that, SolidJS provides the onCleanup function.

As a rule of thumb, onCleanup can be called wherever there is a scope that would get cleaned up at some point. For example, once a component is no longer being rendered, it needs to be cleaned up and removed from the DOM. By calling onCleanup in the component body, you can add an extra callback that will be called when that happens.

For reactive effects (createRenderEffect/createEffect), calling onCleanup inside the effect callback will schedule a function to run when the effect is re-run, i.e. when a signal triggers the effect to restart, all onCleanup functions will get called, and then the new effect is run.

In general, put your onCleanup calls inside the function you use to create your side effect in the first place. For example:

// NO!  Don't do this!
onMount(() => {
  /* some side effect */
});
onCleanup(() => {
  /* some clean up */
});

// ----

// YES!  Do this!
onMount(() => {
  /* some side effect */
  onCleanup(() => {
    /* some clean up */
  });
});

This is because generally you only want the onCleanup to run if the side effect was called in the first place. As mentioned earlier, functions like onMount and createEffect will not run during SSR, but if the onCleanup isn’t inside one of those functions, then it will still be called during SSR, doing unexpected things.

Addendum: Avoiding effects

At the start, I made the comparison to React’s useEffect, and in a footnote pointed out that in modern React, useEffect is generally discouraged — there’s often a better way.

In SolidJS, createEffect doesn’t behave in quite such surprising ways as useEffect, thanks in large part to the automatic dependency tracking that means that the effect normally re-runs when you’d expect it to re-run. However, it’s still a good idea to look out for cases where you can replace createEffect with a better option. When I look at createEffect calls, these are the things I’m looking out for:

• Is a signal setter being used in the body of the effect? If so, the effect can almost certainly be replaced by createMemo or another form of computed signal.
• Is an async function being called in the effect? If so, it might be worth using createResource (or createAsync from Solid Router) instead, as this will handle some of the boilerplate for you, as well as integrating with the suspense mechanism.
• Is the effect setting an event handler on a DOM element? If so, use the on* handlers in JSX instead. This seems obvious, but I’ve written this sort of code before, only to realise later that I’d missed an obvious and easier solution.
• Is the function body reactive and/or would the effect work better if it was run immediately? As discussed in this article, other functions for running side effects are available.
• Is there a function that already handles this case in a Solid Primitives package, or can you write your own wrapper around the effect to encapsulate it a bit better? This one isn’t really about getting rid of effects, but rather hiding them somewhere else. But encapsulation is good, and the Solid Primitives functions are generally useful, even if you’re just looking at the source code to get a hint of how to do something.

The problem happens with an application that looks something like this:

const app = Fastify();

app.register(ws);
app.register(fastifyCookie);
app.register(fastifySession, { secret: "..." });

app.register(fastifyTRPCPlugin, {
  prefix: "/trpc",
  useWSS: true,
  trpcOptions: {
    router,
    onError,
    createContext: ({ req }) => {
      console.log(req.session); // logs "undefined"
      return {};
    },
  },
});

The useWSS parameter passed to the tRPC plugin means that it can handle both standard HTTP requests and a persistent websocket connection. Theoretically, both of these kinds of requests get handled by Fastify first, and therefore both should be initialised with a session object¹. In practice, though, the session field is missing on all websocket-based connections, but present for all HTTP-based connections.

The cause is that the Fastify adapter for tRPC delegates to the non-Fastify-specific websocket adapter. When that creates a context, the incoming req object is an instance of IncomingMessage, i.e. the underlying NodeJS request abstraction, which does not have the Fastify session details attached.

This probably should be better documented, ideally directly in the types (although that would probably be a fairly large breakage), or at least in the Fastify documentation.

The best solution I found is a WeakMap mapping IncomingMessage requests to FastifyRequest values, which have the expected session attribute. That looks something like this:

// create a new scope so that the hook we add later will only
// affect tRPC-specific requests
app.register((app) => {
  // use a WeakMap to avoid leaking memory by holding on to
  // requests longer than necessary
  const REQS = new WeakMap<
    FastifyRequest | IncomingMessage,
    FastifyRequest
  >();

  app.addHook("onRequest", async (req) => {
    // associate each raw `IncomingMessage` (`req.raw`) with
    // the original `IncomingMessage`
    REQS.set(req.raw, req);
  });

  app.register(fastifyTRPCPlugin, {
    prefix: "/trpc",
    useWSS: true,
    trpcOptions: {
      router,
      onError,
      createContext: ({ req }) => {
        // given either a `FastifyRequest` or an
        // `IncomingMessage`, fetch the related
        // `FastifyRequest` that we saved earlier
        const realReq = REQS.get(req.raw ?? req);
        if (!realReq)
          throw new Error("This should never happen");

        console.log(realReq.session); // logs the session object
        return {};
      },
    },
  });
});

Because the tRPC types aren’t correct for the req parameter of the createContext callback, you might need to fiddle with the Typescript types to get this to work properly. Specifically, the WeakMap type here is technically incorrect, but means that I can do REQS.get(req.raw ?? req) without Typescript complaining. This does cause an ESLint error (because according to the type definitions, req.raw can never be null), but I’d rather silence an ESLint error than a Typescript error.

I hope this helps you, or myself in six months’ time when I run into this issue again having forgotten about it completely.

The channel is so compelling because they don’t just focus on getting the right answer, but explain how they can make each deduction along the way to figuring out the puzzle. They often use the language of proving: it’s not enough to guess, or to believe, or even to be very confident that a particular number needs to go in a certain place, you have to prove that it’s correct. Generally that involves whittling away at the other options and showing that they don’t work. If we know a number needs to go in a certain row, but the rules prevent us from putting it in any other cell in that row but one, then we have proved that the number must go in that cell.

There’s still a lot of intuition involved though! With many years of experience, Simon and Mark are able to look a few lines and the grid and very quickly find which parts of the grid they should be looking at first. When I started playing along and trying to solve some of the simpler puzzles myself, this was what I found most hard, but over time I’ve found I can spot “naked singles”, “roping”, or uses of “the secret” (all real sudoku terms) just by running my eyes over the grid.

But that intuition is only a start, and it can be wrong (or even deliberately mislead). Intuition might tell you something like “I should think about where the number five can go in this column”, because a particular rule makes it hard to put fives in certain places. But I can’t just guess where the five will go — I need to prove that, and show that no other option is possible. There’s an interplay between using human intuition to guess where the next weak spot will be, and then taking a more mechanical approach to actually put numbers into the grid.

So what does this have to do with programming?

Sudokus, to me, feel most useful when debugging. Not necessarily the sudoku puzzle itself (although taking a break to do a sudoku can be a great way to clear my head), but the headspace that it invokes. Debugging involves the same interplay between intuition and proof that a sudoku does, and I use a similar approach in both cases.

The first thing I want to do when I’m debugging is get as much of an overview of what’s going on as possible — logs, error messages, videos of what the user was doing, etc. This is like looking at the whole sudoku grid and trying to guess where you should look next. You won’t necessarily know exactly what to do, but you can build up hunches for where to look.

This hopefully gives me a clue as to which area of the code to start looking at. Now I want to start eliminating possibilities. What can I prove isn’t the cause of the problem? I find deleting or commenting out code is a fantastic tool. If I’m feeling particularly paranoid, I’ll even start deleting logs and other code that feels obviously irrelevant, just to eliminate those as options.

Even with a smaller set of options, there still might be multiple places to look. At this point, often I find it helpful to reason through the different options. In a sudoku puzzle, I might know that a certain cell must be 1, 4, or 9 (say). Then I can reason that through: if I made this cell 1, what would happen? What would the effects be?¹

When debugging, I do something similar. Here, though, it’s often more useful to think about how this bit of code might cause the effects I’ve already seen. Say there’s been issues with connection failures: how could the code I’m looking at have triggered those failures? And would it have produced the same sorts of errors, or would it have looked differently?

I often have cases where I think “oh, there could be a bug here, but it wouldn’t explain why XYZ also happened”, or “if this were to cause a bug, it would happen by the server crashing, but the server never crashed”. Sometimes this is even a trigger to go out and look for more evidence. Am I sure there wasn’t a server crash? Am I confident that there’s no relationship between this code and XYZ?

Hopefully I’m confident now that I’m in the right place. Maybe I can already see what I’ve done wrong, maybe I need to fiddle with the code some more, but let’s assume I eventually come up with a cause for the bug, and a way to solve the bug.

However, the final step is to prove that this really was the cause for the bug, and that the solution really is fixing the root cause. It’s not enough that I just can’t see the problem any more — that’s like putting a number into the grid because you think it’s more likely to be in one place than the other. With sudoku and with debugging, certainty is important.

I’ve seen some suggestions that the way to know whether or not you’ve fixed something is to find a way to trigger the bug reliably, and then add and remove the fix. If you can consistently see that the bug is gone with the fix, and present when the fix is removed, then you’ve fixed the bug. There’s some truth to this, but I think it’s only part of the story. More important is being able to say — as precisely as possible — why the bug occurred, and how the fix stopped it from happening. That’s the “proving” part: understanding at a deeper level what’s going on and how to stop it.

A perfect analogy?

It’s important to remember that a sudoku is a puzzle designed to have a single solution, and usually a single path to that solution. Debugging is not part of anyone’s plan, there may not be a single cause to the problem, and there are often multiple solutions to the problem once you’ve found it. However, I’ve found the strategy of puzzling — particularly the style of sudoku solving from Cracking the Cryptic — is a useful way to approach debugging. This strategy keeps me from relying too heavily on untested assumptions, and keeps me going until I find an actual cause, and not just a vague suspicion.

Okay, so maybe ten years isn’t all that long, but since I started studying software development properly, I’ve learned a lot, and I want to reflect on that a bit. I suspect not everything I learned is correct: come back in ten years’ time to read my critical retrospective where I point out what an absolute idiot I was/am. But in the meantime, here are some assorted thoughts on how I practice programming.

• I write software for people. No, literally, I write code thinking about the people who will read it. When I write a blog post or an email, I’ve got a target audience in my head. Why not do the same thing with code? Is this clever type-level shenanigan really the best idea? Will my colleagues be able to quickly extend this test file with new cases? Would a comment be useful here?

• The more I automate, the less I have to think. I don’t think I can write code without an autoformatter any more. The junk that comes out of my keyboard is bad — all on one line, indentation all over the place, terrible spacing. But an autoformatter does the tedious formatting work for me. I don’t even care what that formatting is — I will accept basically anything, as long as I don’t have to think about it. See also: automatically importing functions I’m using, as well as automatically removing imports I’m no longer using.

• The more I automate, the less I have to think: Round 2. This goes doubly if the stuff I’m automating is stuff I only rarely do. I have a few projects that I occasionally do stuff with — a LaTeX CV that I only update when I’m looking for a job, a website that only needs occasional changes, etc. Automation (a Makefile, a CI build/deploy pipeline, etc) means I don’t have to reverse engineer the project every time I come to work on it again.

• Some things aren’t automatable. Whenever I commit my code, I diff my code and try and review it to see if I’ve made silly mistakes, left debugging code in, forgotten to refactor something, etc. Then, when I create a pull request, I do the same thing again. Linting isn’t a good substitute for this — it can catch some of the basic stuff, sure, but it won’t catch anything. I haven’t (yet) found a way to automate away simple diligence.

• The right programming language is important, but probably less so than I’d like to believe. When I first learned to program, I used Python, and then I ended up in the frontend world and started writing a lot of Javascript, then Typescript, and it just hasn’t really stopped. And you know what? Javascript is not a great language. But it’s good enough. I write a lot of my own stuff in Rust and miss features of Javascript, then spend my day job missing things in Rust (or Python, or whatever else).

• Types are non-negotiable for large projects. Okay, yeah, all programming languages have something good about them, even the bad ones, but the more people you work with, the more tools you need to communicate how code works. And types are possibly the single most effective tool to communicate how code works. Tests are cool, documentation is great, but both can be ignored or overridden. Types (okay, well-written types) stick around and enforce their rules on the codebase.

• I like tests when they’re good. I’ve written before about how I didn’t really get testing until I understood how to write a good test. I’m currently rewriting a core module in a system at work, and having 100 or so tests that each test one aspect of this module, that I can slowly reenable as the new functionality comes online — it makes my life easier, and gives me more confidence that my new version behaves the same as the old.

• I hate tests when they’re bad. I still struggle to delete tests — it feels a lot like cheating — but sometimes they just aren’t helping. The accuracy and precision of tests in large codebases would be a great topic to study, because I suspect a lot of tests are never once useful in their lifetimes in a codebase.

• The simplest code is usually the hardest to write. There’s that famous quote “I’d have written a shorter letter, but I didn’t have the time”. I have similar feelings about code simplicity. Simple code isn’t about writing less code (that’s usually code that’s missing edge cases). It’s also not necessarily the easiest to read (see Torvald’s “good taste” example, which is simple, but uses more indirection than a more naive alternative). Simple code is good, but it usually takes a lot of work to create it¹.

• Perfection is a good goal, but a bad obsession. I really like doing things the “right” way. I’m one of those people who’ll come up with an idea, create an empty repo for it, and then spend the next three hours getting the tests, linting, and CI working. I say that partly in jest, but also partly in pride. Perfection is also about little things like choosing the right semantic HTML element rather than adding an onClick handler to a div ; or spending a bit of extra time to get the commit history looking cleaner; or finding the O(n) algorithm instead of the O(n²) one.

  But I’ve also got to limit myself on these things. Sometimes it’s not worth the extra effort. Sometimes, it’s not even possible to get things perfect. Often, there are competing needs, and I just choose the needs that feel most important at the time. I recently saw a comment where someone listed their ideal websites, and it included things like not using CDNs, and ensuring that the site works on terminal browsers like Lynx. The perfectionist inside me understands these goals, but the pragmatist has won out, at least for this website.

I’ve been thinking about this question a lot recently. I’ve been trying to motivate some teammates that tests are worth writing. But I’m going to convince them of that, I need to be able to answer that question for myself, right?

Tests sometimes get portrayed as one of the chores of software development. As a new developer, that’s how I saw tests for a long time: something I did because it was what I was told to do — besides, if I got the coverage to 100%, I got a little green checkbox to put on my README.md file on Github. I knew that tests were good, because they make Good Code™ — I just didn’t know how that happened, or why my tests were still so painful to work with!

But over time, I’ve found better ways of writing tests, tests that are easier to write and work with. And once I started writing better tests, I found they also became more useful to me, and I wanted to write them more — not because of some coverage metric, but because I was getting real value out of them.

Now, trying to articulate the “why” of testing to others, it’s been interesting to explore where that value is coming from. The more I write tests, the more they’ve become another tool in my toolbox — another way of developing faster and more confidently. It’s like learning all the shortcuts in your IDE or editor of choice, or figuring out the underlying model behind Git: the better you can use the tool, the more useful the tool is when you’re developing.

In this post, I want to explore testing as a tool in the process of building software. I’m going to divide my test-writing process into two parts: testing as a tool for faster development, and testing as a tool for future refactoring. I’ll talk about each part individually, and then explore how the two parts work together. Throughout this, I want to argue that testing is not just about correctness, but also that it can be an integral part of the development and design process.

Testing for Faster Development

When I started programming, I did testing like this: I would write my code, and then I’d run it. And that was pretty much the full test. I’d run the program I’d written a few times with different arguments or inputs and make sure it was doing what I expected.

This strategy works really well at first. You try out your code by using it — how can there be any purer approach? And it’s really easy to get started too. No boilerplate, no extra frameworks; just run the code and poke around a bit until you’re confident that it works.

Unfortunately, as a strategy it also falls apart quite quickly too! The more states there are to test, the longer the testing process takes, and the higher the chance of forgetting an important case. Without a proper strategy, it’s very easy to go around in circles, fixing one thing only to break another thing in the process.

Solving this situation was my first introduction to automated testing: tools like pytest gave me a way to run lots of tests at once, so that while I was making changes, I could see immediately when something was broken. The immediate feedback made it easier to develop quickly — the faster I could see what effect my changes had had, the faster I could decide if those changes made sense, and iterate on them further.

These days, it’s that desire for immediate feedback that often drives me to start writing tests. Right now, for example, I’m working on a project that involves tracking focus (i.e. which pane of the UI is the user interacting with at any point in time). Handling all the events and possibilities there involves a lot of edge cases, but writing tests for all of the edge cases that I come across means that I can see at a glance if what I’ve fixed, what I’ve broken, and what’s stayed the same.

It also makes it easier to try different things out. I can write exploratory code very quickly: once I’ve defined my goal, I can try out different ways of achieving that goal. Is it the focus event that does what I want, or the focusin? I can try both out and see which one has the effect I was after. Does this function automatically clean up after itself? Let’s find out by writing a quick test.

Development tests need to be quick, both to run and to write. The faster they run, the faster you get feedback (and the more you can run at once). But being able to write new tests quickly is also key. Writing tests adds to development time, but also adds a certain amount of context-switching between code and test, which we ideally want to reduce.

In my experience, there are a couple of keys to writing simple tests. Firstly, you need simple code (and in particular simple interfaces¹). A test that requires priming three different mocks with precise behaviours is going to take a lot longer to write than a test that involves passing a couple of arguments to a function.

Secondly, it’s important to find good abstractions inside the tests. Abstraction in tests can often be seen as sacrilegious, but if tests are part of the codebase, then we should write them like code, including (cautiously) using abstractions. But I want to save some of my thoughts on that for a future blog post.

Testing for Future Refactoring

The goal for refactoring is to keep the outward-facing interface of a unit (say, a module, a class, a function, etc) the same, while rewriting the internals to be more maintainable. This naturally raises the question: How do define that outward-facing interface of a module in the first place?

One answer is tests. If you’re adding tests to a unit for development purposes as you go along, over time you’ll build up a collection of examples of how that unit works. For example, a test that asserts that add(1, 2) results in 3 tells me a bit about the outward-facing interface of the add function². That’s a useful way of defining this interface, in large part because we can automatically run these tests regularly to make sure that the interface remains the same.

However, using tests to define our interface brings with it a couple of difficulties that we need to deal with.

The first difficulty is figuring which areas of a unit to test: what is part of the outward-facing interface, and what are internal details that aren’t really relevant? In one of my first jobs, I worked on a codebase that had plenty of tests, but those tests included assertions for the exact message, context, and order of every single log call. Those tests were painful to work with — even small changes might change some aspect of the logs, which meant continually updating dozens of tests.

Tests that check internal details like this make refactoring harder. Maybe I decide to work around the tests to keep them passing, even though I know no code depends on the behaviour they’re checking. Maybe I make the changes regardless of the tests, and now need to update a bunch of tests to match the new observed behaviour. Either way, it’s more effort to make the change, and the tests — the tools that should be helping me — are working against me.

The second difficulty is what to do when an interface really should change. If each test makes a claim about the outward-facing behaviour of a unit, what happens when we want to update that behaviour? There are some contexts where we want to avoid changes at all costs — publishing a module for other teams to use, for example. But often the team writing the unit also wrote all of the places where it was used. In that case, it might be easier to update all the call-sites rather than trying to work around an existing interface.

In this case, having tests break is good (otherwise are the tests really telling us what’s going on?), but it’s still work, time, and effort to fix them. A good test, therefore, is also easy to update. Similarly to testing for development, one tool here is abstraction. Describing test goals at a higher level (e.g. “Which suggestions would I get if I typed in this text, and left the cursor at this point?”) allows a chance to abstract the precise mechanics of that code, while still maintaining the same tests.

The third difficulty is figuring out where to stop testing. If I fully tested every single function, every method and class, then I’d never be able to change my code without needing to update a whole bunch of tests to match. At this point, tests are slowing me down rather than speeding up.

When I’m refactoring, the best tests are the ones that are written against interfaces that are unlikely to change (or at least, unlikely to change beyond what can be fixed with a bit of find-and-replace and some manual poking around). In particular, modules that represent core business logic are generally unlikely to change significantly — if your application is a spreadsheet, then the module handling the reactive engine that binds all the cells together is going to need to remain relatively consistent. This can also be true for smaller modules that narrowly focus on one piece of functionality.

Design: Combining Development and Refactoring

I’ve presented these two ideas as if they were two different testing processes, and in a way they are: if you were to only do testing for development, you’d probably choose to optimise a different set of things to if you were only doing testing for refactoring. But in practice, most of the tests I write serve both needs. After all, it would be a lot of effort to develop an entire test suite as I’m developing my code, only to delete it all and rewrite it for future refactoring purposes once I’ve finished.

I think that combining development and refactoring into one set of tests is about good software design.

In Test-Driven-Development (or TDD), there’s a big emphasis on tests as a tool for design. But often that connection between testing and design is explained poorly, or not at all. I regularly see references to TDD having the “refactor” stage, or an argument about how testing things helps us break them down into modules, but I think we can be more specific about this.

My theory is that good, clean code comes from a balancing of short-term and long-term needs, and the development/refactoring divide brings both of those needs to the surface. My short-term, development tests push me to write simple code. If it takes me thirty lines of code to get my code set up properly before I can even start testing, then development is going to be a very slow process! But my long-term, refactoring tests push me to write code that has clear public boundaries. After all, I don’t want to rewrite my tests every time I make a change to the implementation.

If I concentrate too hard on one kind of test or the other, then I will run into issues. If I’m only testing for development, then my code might be easy to get running, but I’ll probably need to delete all the tests next Wednesday when I make a slight internal change that breaks all of them. If I’m only testing for the sake of refactoring, then I can construct a labyrinthine maze of interfaces, dependencies, services, and end up with a kind of Enterprise FizzBuzz-style mess.

It’s the combination of testing for now and for the future that makes tests useful as a tool for software design.

Conclusion

In this post, I’ve tried to present my approach to testing as, principally, a tool for making my life as a software developer easier: it allows me to write code more quickly by providing a way to check that what I’m writing works; it allows me to refactor more confidently by enforcing that what I’m writing adheres to a certain interface; and it encourages better design through the natural pressures that come from the tests I’m writing.

Like I said at the start, the value here isn’t just some arbitrary vision of what Good Code™ should look like, or even correctness. (I’d go as far as to say that making code correct often involves a lot more than just tests, and tests are just one small part of that, but I’ll bang the static typing drum some other time.) Writing tests makes me faster overall³, and more confident in my work. I made the comparison earlier to an IDE, and it feels similar. As a developer, an IDE isn’t necessary, but it will highlight my code, identify unused variables, allow me to navigate the codebase I’m working on easily, and generally make my life easier. Tests are a form of that that have the added convenience of being shared by my entire team.

A huge thanks to matklad, who kindly looked over a draft of this post and offered his thoughts.

The Journey to Using using

Many classes or objects represent some sort of resource, such as an open file or a database connection, that requires some cleanup logic when that resource is no longer in use. In NodeJS, the convention is typically to put this cleanup in a close() function. For example, the Server class in node:http has a close() method that stops new connections and closes existing ones.

The problem with close alone is that it’s easy not to call it. Sometimes it’s a matter of forgetting, but often errors and exceptions can trip us up. Consider this function:

async function saveMessageInDatabase(message: string) {
  const conn = new DatabaseConnection();
  const { sender, recipient, content } = parseMessage();
  await conn.insert({ sender, recipient, content });
  await conn.close();
}

This creates a database connection at the start of the function, and closes it at the end. But we have a problem if parseMessage or conn.insert(...) throw an error — in this situation, the saveMessageInDatabase function will stop without closing the connection, leaving unclosed resources hanging around.

The first step to solving this is to formalise how a resource gets closed. We can do this using the Disposable interface or protocol:

interface Disposable {
  [Symbol.dispose]: () => void;
}

This is very similar to methods like .close(), .cancel(), and so on, but we use the well-known symbol Symbol.dispose instead. This helps the runtime to distinguish between objects that have been intentionally made disposable (using this symbol), and objects that happen to have a certain name (e.g. door.close()).

With this in place, we can define the using syntax. using can be used in much the same way as const, and behaves very similarly in most respects.

// was: const varName = new MyDisposableObject();
// now:
using varName = new MyDisposableObject();
varName.method();

However, using has a couple of restrictions in addition to the normal behaviour of const:

• With using, the variable must implement the Disposable protocol — i.e. it must have a Symbol.dispose method that can be called without arguments.
• With using, you cannot destructure the variable you’re interested in (e.g. using { field1, field2 } = disposable()).

When we leave the scope where a using variable was defined (i.e. when we return from the function in which using was used, or leave the if-block, or an exception gets thrown, etc), then the Symbol.dispose method will be called.

In addition, the dispose methods will be called in the reverse order to the way they were defined. So the object that was created first will be disposed of last. This reverse order is deliberate: we don’t want the database to be cleaned up while other resources are still using it!

An example:

function create(data: string) {
	console.log(`creating disposable object with data ${data}`);
	return {
		data: data,
		[Symbol.dispose]() {
			console.log(`disposing disposable object with data ${data}`);
		},
	}
}

function main() {
  using data1 = create("first");
  using data2 = create("second");

  console.log(`using ${data1.data} and ${data2.data}`);
}

console.log("before main");
main();
console.log("after main");

This will produce the following logs:

before main
creating disposable object with data first
creating disposable object with data second
using first and second
disposing disposable object with data second
disposing disposable object with data first
after main

Async Disposables

Often, when we want to dispose of a resource in Javascript, that cleanup/close/disposal operation will need to be asynchonous — for example due to waiting for connections to be cleaned up or data to be flushed.

So in addition to the standard Disposable protocol, there’s a second one, AsyncDisposable. This uses the Symbol.asyncDispose method, which returns a promise that should resolve when the resource is completely closed.

To use an async disposable, we have the await using syntax, which does the same thing as a normal using declaration, but, well, asynchronously. It must be called inside an async function (i.e. it needs to be called in a place where normal await is allowed).

The await using syntax can also handle non-async Disposable objects, which means if you don’t know whether a given resource is going to be asynchronously or synchronously disposed, you can use await using and cover both options.

Collections of Disposables

Sometimes it’s not enough to use function scope to handle resources. We might have a class or object that owns and manages a number of different resources. It would be useful if we could group all of its resources together in a similar way to using, but as a class variable or as part of a closure.

One convenient way of doing this is using the DisposableStack and AsyncDisposableStack classes. These represent stacks of resources managed by the DisposableStack or AsyncDisposableStack object — if we clean up the stack, all the resources that it manages will also get cleaned up. They can be created using the new operator, and provide three different methods for adding resources to the stack:

const stack = new DisposableStack(); // or ` = new AsyncDisposableStack()`

// .use() takes a resource, adds it to the resources managed by the stack,
// and returns the resource so it can be used elsewhere.
// The resource must be a disposable item using the `Symbol.dispose` method
// (or `Symbol.asyncDispose` if using `AsyncDisposableStack`).
const resource1 = stack.use(new MyResource());

// `.defer()` schedules a callback to take place when the stack gets disposed.
const handle = setInterval(() => console.log("running"), 5000);
stack.defer(() => clearInterval(handle));

// .adopt() combines the above two behaviours: it takes a resource and a
// disposal callback, and calls the callback with the resource as its argument
// when the stack gets disposed.  The resource does _not_ need to implement
// the disposable protocol.
const resource2 = stack.adopt(new OtherResource(), (r) => r.close());

Stacks are themselves disposable, so can be disposed of using the Symbol.dispose or Symbol.asyncDispose methods. For convenience, this method is also exposed simple as .dispose() or .asyncDispose(). As mentioned earlier, this method (either using Symbol.dispose/Symbol.asyncDispose or via the alias method) will dispose of all of the resources managed by this stack. Similarly to the using declaration, the resources will be cleaned up in reverse order to prevent issues where resources depend on each other.

Useful Patterns with Explicit Resource Management

Hopefully by now it should be clear what disposable resources are, how they can be manipulated, etc. But it still took me a while to get my head around some typical patterns with disposables, how they can be manipulated, and some best practices. So here are a few short sections which explain a couple of ideas that are now possible, and the best ways to achieve some common goals.

Anonymous Defers

If you’re coming from other languages with features similar to using, such as Go with its defer statement, then you may be surprised that using is really a variable declaration — it’s basically the same as const or let, but it also automatically cleans up resources when the function has completed.

As a result, every time you use using, you need to declare a variable name. But often you don’t want to specify a variable name — e.g. if you want to defer a callback until the end of the function. It’s possible to do something like using _ = ..., using _ as a kind of informal placeholder, but this only works once per function body.

The best solution I’ve found is DisposableStack (or AsyncDisposableStack) and the defer method:

function main() {
	using stack = new DisposableStack();

	console.log("starting function");
	stack.defer(() => console.log("ending function"));

	console.log("during function body");
}

Disposable Timeouts and Intervals

The specification gives a list of various browser and JS APIs that will be retrofitted with the disposable mechanism, but one API that is noticeably missing is the setInterval and setTimeout functions. Currently, they can be cancelled using the clearInterval and clearTimeout functions, and we can use defer to integrate them into a disposable stack:

function main() {
	using stack = new DisposableStack();

	const handle = setInterval(() => {/* ... */}, 5000);
	stack.defer(() => clearInterval(handle));

	// ...
}

In fact, if you’re using NodeJS, you can go one better. The NodeJS timers (i.e. setInterval and friends) already return an object (Timeout) with lots of useful functions like .unref(). Recent versions of v18 and upwards now also include a Symbol.dispose key for these objects, which means you can simplify the above code to this:

function main() {
	using setInterval(() => {/* ... */}, 5000);

	// ...
}

And in the browser, we can write a similar utility function:

export function interval(...args: Parameters<typeof setInterval>): Disposable {
  const handle = setInterval(...args);
  return { [Symbol.dispose]: () => clearInterval(handle) };
}

The Use-and-Move Maneuver

One more subtle but incredibly powerful method in the DisposableStack arsenal is .move(). This creates a new stack, moves all of the resources in the current stack into the new stack, and then marks the original stack as disposed. None of the resources will be disposed except for the original stack.

This is a powerful tool for anywhere where you’re creating resources for use elsewhere (so you want to put them in a stack), but the very act of creating resources is something that might fail (so you want to be using that stack when you create them.

Consider this example, which can cause resource leakages:

export function badOpenFiles(
  fileList: string[]
): { files: File[] } & Disposable {
  const stack = new DisposableStack();
  const files = [];
  for (const fileName of fileList) {
    files.push(stack.use(open(fileName)));
  }

  return {
    files,
    [Symbol.dispose]: () => stack.dispose(),
  };
}

If I call this with a list of files, it’ll open all of those files and return them as single disposable object, that when it gets disposed of, closes all the files again.

But let’s say I call this with the file list ["file1.txt", "file2.txt", "file-does-not-exist.txt", "file4.txt"]. Now, the first two files get created and added to the stack, but the third one causes an error, which exists the function. But because the stack was never added to a using declaration anywhere, those files will never be closed, which causes resource leakage.

The .move() function allows us to do this instead:

export function openFiles(fileList: string[]): { files: File[] } & Disposable {
  // Note we use the stack here, which means this stack will be cleaned up
  // when we return from the function.
	using stack = new DisposableStack();
	const files = [];
	for (const fileName of fileList) {
		files.push(stack.use(open(fileName)));
	}

	// We've successfully created all the files with no errors.
	// Move the opened file resources out of the stack, and into a new
	// one that won't get closed at the end of this function.
	const closer = stack.move();
	return {
		files,
		[Symbol.dispose]: () => closer.dispose()
	};
}

The Disposable Wrapper

Right now, Disposables are still relatively new, and so it’s not unlikely that the library you’re working with doesn’t support them, opting instead for a .close() method or something similar. But Javascript is a dynamic language, so it’s not too hard to get these tools to behave. Here’s an example for MongoDB, which at the time of writing does not support using or any of the disposable protocols:

function createMongoClient(
  connection: string,
  options?: MongoClientOptions
): MongoClient & Disposable {
  const client = new MongoClient(connection, options);

  if (client[Symbol.asyncDispose]) throw new Error("this code is unnecessary");
  return Object.assign(client, { [Symbol.asyncDispose]: () => client.close() });
}

This will add a Symbol.asyncDispose method to the client, meaning you can use it in await using declarations and with AsyncDisposableStack#use(). In addition, if you ever update to a version of MongoDB that does implement the AsyncDisposable protocol, you’ll get an error reminding you to delete the code.

Awaiting Signals

A common pattern for NodeJS servers is to start up the web server, and then add event handlers for the OS’s “quit” signals (e.g. SIGINT). Inside these handlers, we can shut the server down, clean up resources, etc.

This works fine, but the control flow can be difficult to follow, and we have to manually call the Symbol.dispose and Symbol.asyncDispose methods where that’s relevant. It would be nice if there was a way to tie the lifetime of the application to the lifetime of a single function, so that when that function exits, the server will also automatically exit, closing and disposing of all resources along the way.

Enter NodeJS’s once function, which converts an event into a promise¹:

import { once } from "node:events";

// waits until the `SIGINT` signal has been triggered, e.g. from Ctrl-C
await once(process, "SIGINT");

Using this, we can write a main() function that lives for the entire length of the application, and quits when the application is stopped, automatically cleaning up any resources after itself:

async function main() {
  await using stack = new AsyncDisposableStack();
  await using resource = createResource();
  // ... etc, for as many resources as make sense

  // alternatively, use the "Disposable Wrapper" pattern from earlier
  const server = stack.adopt(express(), server => server.close());

  // add routes, use resources, etc
  server.get(/* ... */);

  logger.info("starting application on port 5000");
  server.listen(5000, () => logger.info("application started"));

  await Promise.race([
    once(process, "SIGINT"), // Ctrl-C
    once(process, "SIGTERM"), // OS/k8s/etc requested termination
    // etc.
  ]);

  logger.info("shutting down application");
}

Because all of our resources are managed either by using directly, or by the stack which is in turn tied to the application’s lifespan, we don’t need to manually close anything after the signals have been handled — everything will automatically be gracefully shutdown.

Using Explicit Resource Management Today

Right now, explicit resource management is a stage three proposal — that means that the specification has been completed and approved, and browsers and other tools are encouraged to start implementing the proposal, and trying the feature out in practice².

This means that if you want to try this feature out right now, you’re going to need to transpile the syntax to a format supported by older browsers, and provide a polyfill for the various global objects that the feature requires.

In terms of transpiling, both Typescript and Babel support the using ... syntax. For Typescript, you’ll need version 5.2 or greater to handle the syntax. In the tsconfig.json file, the target should be ES2022 or lower in order to do the transpilation (otherwise Typescript will leave the syntax unchanged), and the lib setting should include esnext.disposable (or alternatively the whole esnext bundle of types) to ensure that the right set of types is included. For Babel, including the stage-3 preset, or explicitly adding the @babel/plugin-proposal-explicit-resource-management plugin should ensure that everything gets compiled correctly.

Neither Typescript nor Babel include a polyfill for the various global types discussed here, which means you’ll also need a polyfill. For this, there are various options, including disposablestack, which I’ve been using, and CoreJS.

Bringing It All Together

Let’s say we’re writing something on the backend, and there’s a lot of interactions with users. We want a class that handles all of our user-based logic:

• It can create/read/update/delete our user objects in the database
• It automatically deletes users that haven’t been active in the last five minutes (we’re very GDPR conscious here, we don’t keep data a second longer than we need to)
• It provides a stream of all the new users inserted into the database, so that elsewhere we can send them a lovely greeting message.

We’ll use dependency injection so that we don’t need to create the database connection ourselves, but some of the resources will be managed by the user service. We can use the AsyncDisposableStack to group those resources together, and we’ll add a Symbol.asyncDispose method that delegates to the stack’s dispose method to handle that disposal. We can even implement Typescript’s AsyncDisposable interface to make sure that we get everything right:

export class UserService implements AsyncDisposable {
  #conn: DB.Conn;
  #stack = new AsyncDisposableStack();
  #intervalHandle: NodeJS.Timeout;
  #streamHandle: DB.StreamHandle;

  constructor(conn: DB.Conn) {
    // Our DB connection, passed in via dependency injection -- so we don't want
    // to add this to the set of resources managed by this service!
    this.#conn = conn;

    // Remember, NodeJS's `Timeout` class already has a `Symbol.dispose` method,
    // so we can add that to the stack
    this.#timeoutHandle = this.#stack.use(
      setInterval(() => this.deleteInactiveUsers(), 60 * 1000)
    );

    // For resources that don't have the right methods, `.adopt()` is the
    // easiest way to add an "on dispose" cleanup function
    this.#streamHandle = this.#stack.adopt(
      this.#createNewUserStream(),
      // Closing this stream is an async operation, hence why we're using
      // Symbol.asyncDispose, AsyncDisposableStack, etc.
      async (stream) => await stream.close()
    );
  }

  async [Symbol.asyncDispose]() {
    await this.#stack.dispose();
  }

  // ... methods and implementation details
}

Now we need to actually construct all of our resources somewhere. We can add a createResources function that creates the resources, returns a disposable object that cleans up all of the resources together, and also ensures that if an error occurs during resource construction, everything will still get cleaned up gracefully — this is the power of the stack!

export async function createResources(config: Config) {
  await using stack = new AsyncDisposableStack();
  const db = new MyDbDriver(config.connectionString);
  const conn = stack.use(await db.connect());

  // When the stack disposes of its resources, the `UserService` will be cleaned
  // up before the `conn`, which prevents errors where the `UserService` is
  // trying to use a connection that doesn't exist anymore.
  const userService = stack.use(new UserService(conn));

  // Now all the resources have been set up, use .move() to create a new stack
  // and return a dispose method based on the new stack.
  const closer = stack.move();
  return {
    userService,
    [Symbol.asyncDispose]: async () => await closer.dispose(),
  };
}

Now finally, we need to plug all of this into our server implementation, and make sure that everything gets cleaned up when the server gracefully exits. We can use signals and promises to catch the events that should trigger a shutdown, and use the using declarations to automatically clean up any resources.

async function main() {
  const config = await loadConfig();
  using resources = createResources(config);
  using stack = new AsyncDisposableStack();

  // create wrapper functions around APIs that don't yet support disposables
  using server = createFastify({});

  server.get(/* route using resources.userService */)

  await server.listen({ port: 3000 })
  logger.info("server running on port 3000");

  // use `once` to turn one-time events into promises
  await Promise.race([
    once(process, "SIGINT"),
    once(process, "SIGTERM"),
    once(process, "SIGHUP"),
  ]);

  logger.info("server terminated, closing down");

  // resources will all be cleaned up here
}

More Resources

There’s a lot more information out there about the explicit resource management proposal, but given how Google isn’t working as well as it once was, here are some links to help you find it:

• The original proposal in the TC39 GitHub organisation. The documentation is a bit technically-focussed here, but the issues provide a lot of good context for the APIs, and a number of examples that explain why certain decisions were made.
• Typescript 5.2’s release notes include a section about resource management, how to use it, and how to get it working in Typescript.
• Various tickets/bugs/issues about implementing explicit resource management:
  • Chrome
  • Firefox
  • Safari
• Prior art in other languages:
  • C#’s using statement is a big influence here.
  • Go’s defer statement inspired the .defer method.
  • Python’s ExitStack is an explicit inspiration for the DisposableStack and AsyncDisposableStack classes.

You can also find an edited and updated version of this post that I wrote for my employer’s blog here.

A discussion came up on Reddit recently about DI, where I mentioned that one way that I’ve done DI recently for web frameworks that don’t naturally support it to using closures. Someone asked for an example, so I figured I’d explain what that looks like and where it might work (or not work). The original question was about Python, but I’ll give Python and Javascript examples.

I’m going to start with some context of my dependency injection philosophy, but if you want to skip that, you can jump straight to some examples here.

Why DI

The problem I’m trying to solve here is DI, or dependency injection. I have a function, class, or in this case route handler that needs access to a given resource, such as a database connection. As I do that, I have three aims:

1. I want to wrap the database connection in an explicit interface to allow encapsulation — I don’t want my routes to have to know how the database is structured, I just want them to be able to load and save e.g. User objects.
2. I want to be able to parameterize the database connection. When I run the code from my local machine, I want it to point to a local database, and when I run the code on production, I want it talking to the live database. That should happen automatically based on configuration files or environment variables.
3. I want to prevent code from having to construct its own dependencies (i.e. I want inversion of control). I don’t want to create the database connection inside the route handler, I want that to happen outside the route and the result be passed to the route handler in some way.

The solution to this is dependency injection, or DI. When I first started programming, this term confused me for a bit, because I’d see lots of “DI frameworks” or similar tools, and I assumed that DI meant the act of using decorators or annotations to automatically inject parameters into the right place. This is not the case — those tools are often useful, but DI is more about how you write your code in the first place. For example, here are two Python functions, one of which uses DI:

import emails

# Function 1

def send_emails(user: User, message: str):
    emails.EmailMailer().send_email(user.email_address, message)

send_emails(User(name="...", email="..."), "this is an email")


# Function 2

def send_emails(mailer: EmailMailer, user: User, message: str):
    mailer.send(user.email_address, message)

mailer = emails.EmailMailer(**email_params)
send_emails(
    mailer,
    user=User(name="...", email="..."),
    message="this is an email",
)

I think this is a good example, because you can see the advantages and disadvantages of DI. In this example, the second function uses DI, and the first function does not. The thing that jumps out the most to me is that the DI example is much more verbose — it takes more code, and it makes function signatures more complicated because they’re taking more parameters. Partly that’s just how I’ve written these examples, but I do think DI adds complexity — useful complexity, but complexity nonetheless. You don’t need DI if it’s not adding value.

However, there are some benefits visible in the second function. By making the EmailMailer object explicit and bringing it out of the send_emails function, we can now more easily pass parameters to it. If multiple functions are all using the EmailMailer object, and we need to change how we configure it, then now we can do that configuration in one place, rather than at every place that it’s used. (Alternatively, before we might have used some global configuration, but with DI, we can be more explicit.)

We can also swap out the mailer object that we use. I think this is often oversold as an advantage (how often do you really swap out implementations like this?) but it’s often useful for testing. If we want to test the first send_emails function, we’d have to mock a bunch of global imports, but with the second, we can just call the function with a mocked parameter.

The most important thing to notice here is that Function 2 uses dependency injection without going near a DI framework — without even using a single decorator! At its core, DI is just moving things from being constructed inside functions, to being constructed outside functions, and then figuring out how best to pass them back in.

Note that I’ve used functions here, but classes work in much the same way. Typically, parameters can be passed to the class constructor (__init__(), constructor(), etc), and then attach as instance attributes (self.param, this.#param, etc). I’m not going to use that style in this example, but I often use it for service objects.

With that out of the way, this is a way of doing DI via closures.

DI & Closures

Here’s a couple examples of route definitions in FastAPI/Python and in Express/JS:

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id):
    # ... TODO: get item value from a database somewhere
    return {"value": ...}

import express from "express";
const app = express()

app.get("/items/:itemId", (req, res) => {
  // ... TODO: get item value from a database somewhere
  res.json({ value: /* ... */ });
});

As discussed above, dependency injection is about passing parameters to functions. But in the two functions here, that’s difficult, because the parameters are fixed, and we don’t actually call the functions. For example, with the Express example, Express will always call our route handler with the req and res. There’s no place to inject any services or dependencies of our own.

One option might be to attach our dependencies to the parameters. This is common in Express, where middleware can be used to dynamically add a req.users or req.conn attribute that can be accessed inside the routes. However, this can be error-prone, not least because it isn’t compatible with Typescript unless you start modifying global types.

An easier option, at least for simple cases, is often just to use closures to capture the dependencies. Here are some examples to show what I mean:

from fastapi import FastAPI

app = FastAPI()

def add_routes(app: FastAPI, *, item_store: ItemStore):
    @app.get("/items/{item_id}")
    async def read_item(item_id):
        item = await item_store.load(item_id)
        return {"value": item.value}


item_store = ItemStore(db=...)
add_routes(app, item_store=item_store)

import express from "express";
const app = express();

function addRoutes(app: Express, itemStore: ItemStore) {
  app.get("items/:itemId", async (req, res) => {
    const item = await itemStore.load(item_id);
    res.json({ value: item.value });
  });
}

const itemStore = new ItemStore(db);
addRoutes(app, itemStore);

The basic idea is that we move the route definitions from being defined at the top-level to being defined inside a function. The inner functions are now closures — when the function is called, the inner functions will have access to variables defined in the outer scope (in this case the parameters), and so can access the dependencies they need. We can then create all the dependencies, as well as the main app beforehand, and pass them to the addRoutes function.

In practice, I often have a create_context() function that loads configuration from somewhere, creates all the dependencies, and returns Context object or typed dictionary which contains all of the dependencies with keys. Then I can pass that whole context object to builder functions like add_routes(), rather than specifying all the dependencies individually.

Sometimes I also move the app = FastAPI()/const app = express() line inside the builder function, and have it return the entire app. I don’t think one is better than the other, and which I use depends mostly on my mood.

Where This Works Well, or Doesn’t

I’ve used web routing as an example here, but I find this works well enough in any situation where I can’t easily pass something in via function parameters. Most languages I use — even quite static ones like Rust — allow functions to be defined within other functions like this. The key requirement is good support of closures, but this is also fairly standard at this point.

There is an issue if you also want to export the functions somehow. With the FastAPI example above, if we wanted to import the read_item function somewhere else and call it, that becomes very hard with closures. In this case, that’s not a problem, but I’ve run into contexts where it’s more of an issue. In cases like that, I try to decouple the function entirely from any dependencies it needs, and just pass in raw data.

I’ve also noticed that this can be harder to implement correctly in some cases with Rust, if the lifetimes don’t match or the type is difficult to name correctly. Typically Rc/Arc + Clone for services solves most issues, and sometimes boxing up the return value is necessary.

Alternatives

Of course this isn’t the only way! Here are some other options that I also have in mind when deciding how to get my dependencies injected.

• No dependency injection at all — I find this works really well up to a point, and then it stops working fast, usually around the point I’m configuring multiple DBs/external services, and want to get everything running in multiple environments. But simple is better the complicated, and no DI is simpler than DI.
• Using module-level values. In Javascript, for example, I can export a value, as in export const USERS = new UserService(). Similar things are possible in Python and most other more dynamic scripting languages. This can be used instead of DI, and most languages have some way of mocking static module exports, so you can still swap in test implementations. But I find this often ends up quite hacky, and the dependency nest can get quite deep, so I try to avoid this these days.
• A lot of frameworks provide some kind of app context field or value, which can be dynamically updated with different services or connections. Personally, I find it hard to keep track of what’s on the context and what isn’t, and I’ve rarely found a simple way of handling this when I’m using types.
• FastAPI has something it calls DI, but is really just request extractor — it is called for each request, it is passed the request, and it extracts the details it needs. I personally haven’t had much success using this feature for DI proper. That said, other frameworks do provide a full DI framework. If it’s built into the framework, then I tend to follow the “when it Rome, do as the Romans” principle.
• If all else fails, there are lots of DI libraries. I tend to avoid these, because it’s added complexity when just passing in functions works well enough. But sometimes you get to the point where constructing all your services and dependencies up front doesn’t cut it, and you need something more powerful. I’ve not reached that point myself, but most of the projects I’ve worked on have been relatively small.

Conclusion

I hope this was helpful, this is just one strategy that I’ve found useful for doing simple DI without having to lean into frameworks or have annotation/decorator-based magic.

I believe the book we should be recommending is A Philosophy of Software Design by John Ousterhout. In this post I want to spend a bit of time reviewing it and giving an overview of the contents, and then I want to explain why, in my opinion, it is such a good recommendation.

An Empirical Philosophy Book

The elevator pitch of John Ousterhout’s book A Philosophy of Software Design is fairly simple: he is a university professor (albeit one with almost two decades of experience in the “real world”, also the inventor of Tcl, creator of RAFT, company founder amongst other things), who each year teaches students how to actually design software in a practical, hands-on course where the students are expected to design and modify “a substantial piece of software” in an iterative way, hopefully understanding more about the practice of software design each time around.

The book, then, is a synthesis of the pieces of wisdom that Ousterhout has himself learned from his own experiences, tempered and refined by the practical examples he has been able to draw from his students. In this way, it has a (somewhat) scientific, research-based approach, where the author’s assertions are backed up with examples from student projects that worked (or didn’t).

At it’s core, though, this is still philosophy - the book doesn’t just list the things that worked well, and the things that worked poorly. Instead, Ousterhout attempts in each chapter to divine broader truths that apply to software design in general. There are no lists of what to do and what not to do, but instead principles to follow, red flags to be aware of, and warnings against taking anything too far.

Structure

The book is split into a series of chapters, each of which generally explores a single principle. These range from the very high level (“Working Code Isn’t Enough”, “Modules Should Be Deep”) to the more practical questions (“Choosing Names”). The whole book is relatively short (about 180 pages), and many chapters flow together nicely, which means that it’s quite easy to go from cover-to-cover, rather than approach the book as a reference manual. That said, the final pages provide summaries of the design principles and red flags found in the book, making it easy to reference key parts of the book.

Within each chapter, Ousterhout generally starts by stating a problem or motivation that software engineers will face, and then defining a principle to solve this. The rest of the chapter is then a discussion of the principle, the dangers of alternative approaches, the red flags that indicate that the principle needs to be applied (or in some cases avoided), and some notes about taking ideas too far.

The examples are often based on problems that Ousterhout has given his classes, which means that they generally feel meaty enough to be worth discussing. An example of a text editor appears in Chapter 6, but is extended in Chapters 7, 8, 9, and 10 in different contexts. Enough is omitted from most examples to make the point clear, but enough is kept in to give the feeling of real code.

Ousterhout’s Principles

The overriding theme throughout the book is that good code looks good. Ousterhout thinks very much in terms of abstraction and interfaces - where “interfaces” refers to the contact points between different units of abstraction, rather than any similarly-named construct in any particular language. Most of the book is dedicated to figuring out how to spot bad abstractions and rework them into good abstractions.

To a certain extent, this feels at odds with certain common mantras in software engineering circles today, where we encourage enough other to Keep It Simple, Stupid, and worry about premature abstractions. Philosophy seems to worry less about the dangers of over-abstraction, and more concerned with how to make sure that the chosen abstraction is a good one.

This approach makes for a more positive experience than in many other programming circles - rather than being warned into a very conservative approach, Ousterhout encourages his readers to go out and make abstractions, but to be careful about designing the correct ones.

This isn’t to say that the book isn’t also cautionary - in the summary pages at the back, the list of red flags gets more page space than the list of principles, and throughout the book these red flags mark out moments when readers are given the go ahead to use these abstraction techniques. There are also warnings about when a principle might be used too much.

Everyone’s a Critic

Beyond the mild danger of encouraging excess abstraction, the biggest issue in Philosophy is probably the missing parts - the topic of testing gets a single page in Chapter 19 (Software Trends), and ideas about effective use of a type system to avoid issues are largely ignored. Ousterhout’s principles will still apply in these areas, but it would be nice to see some more specific discussion of these areas.

The Target Audience

It can be a bit unclear at times to whom Ousterhout writes. A lot of the examples clearly relate to his students, and the projects that they come from have a somewhat academic feel - a text editor here, and an HTTP protocol parser there. The code in the examples is generally object-oriented (Java and occasional C++), although it generally feels like it could be replaced with most imperative/OO languages without much of an effect.

The use of the phrase “software design” might make one think more of broader software architecture, but Ousterhout uses it more to describe the design of individual modules and functions within a program, rather than the broader architecture of the program itself (although he occasionally touches on that).

More functionally-minded people might think they can simply side-step a lot of the discussion here, in the same way that they can when discussing the Gang of Four’s design patterns, but the principle “design errors out of existence” (Chapter 10) and its corollary “design special cases out of existence” should ring bells for people in this area who are also aware of the principle of making illegal states unrepresentable.

Ultimately, I think this book aims at a space that is slightly deeper than a lot of existing software literature. Where books like Design Patterns, Fowler’s Refactoring, and the aforementioned Clean Code are aimed at more traditional “enterprise” software development, Philosophy feels more widely applicable, albeit at the cost of being more abstract and difficult to apply.

In general, I think Philosophy is a good read if you are both (a) working with software regularly, and (b) conscious of the inherent maintenance cost in software, and aiming to minimise it.

A Book to Recommend

The original question I wanted to answer was what we, as software engineers, should recommend over books like Clean Code. As I said, my answer to that question is A Philosophy of Software Design.

Software engineering (indeed, engineering in general) is not a science, insofar as there are no (or at least very few) exact answers. Everything from the database you use to your choice of testing strategy will be dependent on the context of the software you’re writing. This means that the advice that we give to each other will probably be very context-specific. In general, you probably shouldn’t use a NoSQL database, but in a lot of specific contexts you probably should.

This isn’t a problem if we don’t run into these exceptional cases often, but engineering is all about exceptional cases - if there were no exceptional cases, we wouldn’t need to write any new software, because our existing tools would do the job. This is where books like Philosophy come in - rather than give situational advice, it attempts to define wider principles that the reader will then need to apply to different situations.

Take, for example, my favourite principle: “Modules should be deep” (explored in Chapter 4). The idea is that an individual unit of abstraction should do a lot of work (i.e. be deep, and contain a lot of complexity), but it should have a relatively simple interface (i.e. be narrow). Essentially, if you’re going to abstract something, make sure your abstraction is deep.

Notice that this principle says nothing about functions, classes, lines, blocks, parameters, or anything specific to a single language or paradigm. However, when we apply it, for example to the Java code Robert C. Martin talks about in Clean Code, we can derive some of his ideas from this principle. Assuming a function is our unit of abstraction (for now, at least), the parameters are its interface, therefore we should reduce the number of parameters to the minimum necessary.

However, because our principle is more general, we can actually correct some of the mistakes Martin makes. Martin talks about removing parameters by adding private fields to the class that the method belongs to. When we think in terms of interfaces, we notice that this hasn’t decreased the interface at all - we’ve lost a parameter, but we’ve gained a private field, and in the process made things harder for the consumer of our abstraction.

Teaching Principles Over Rules

When I recommend books, I generally hope that the other person will learn something from the book I have suggested. If I were to recommend Clean Code, I would hope that the reader would learn something about how to write clean Java code, but I suspect they would mainly learn how to write code like Robert C. Martin - or more accurately, like someone copying Robert C. Martin’s actions without always understanding why he’s taking them.

I do not feel this way about A Philosophy of Software Design. When I recommend it, I expect that the reader will not just learn something about Java, but instead something about how to design good abstractions, identify weak abstractions, and write code that is broadly maintainable long into the future.

Updates from the future

• 2021-02-03: Someone on Reddit pointed out that I didn’t sell John Ousterhout enough: he is a very remarkable man. I have updated my description of him to link to that comment, and added some further explanation of his work to the post.