Explaining Software Design

Once upon a time, every project began with the creation of a canonical design document. This was called the system architecture, because it "rightly implie[d] the notion of the arch, or prime, structure."1 Then, documents would be written for each module. These would provide detailed instructions for how the module should be implemented. ...

Previously, we explored how abstract explanations, paired with intent, become specific. And in our case, the intent is almost always to improve our software. But what does this actually mean? To begin, let's consider this metaphor: Things are looking up This is a statement of optimism: things are improving, and we expect this trend to...

There was, in the mid 2010s, a popular formula for explaining a new startup: "Uber, but for ____." This was a metaphor: the startup, despite targeting a different market, was similar to Uber. It was, however, a fairly ambiguous metaphor; there were many ways that a company could resemble Uber. The most visible facet of Uber was their use of a...

In the fractal-metaphor, our software is an open space. Each reader traverses that space, noting new details as they come into view. When our software is well-designed, these details are small and incremental. But this isn't quite right. If it were, movement through our software would satisfy the triangle inequality: In Euclidean geometry, if AB...

In his influential paper On the Criteria To Be Used in Decomposing Systems into Modules, David L. Parnas offers some simple, timeless advice: if two things change together, they belong together. This is not, in itself, an answer. It simply replaces a nebulous question — do these belong in the same module? — with something more concrete. In...

In the software design literature, cohesion is often referred to by a different name: single responsibility. As Sandi Metz explains it: When everything in a class is related to its central purpose, the class is said to be highly cohesive or to have a single responsibility.1 To determine if a method belongs inside a class, Metz suggests posing it...

Sherry Turkle wrote her study of the culture of computing, The Second Self, "on an Apple II computer that had, quite literally, been torn bare."1 Its circuitry had been exposed, and its operating system replaced. Even her word processor felt close to the machine; it required her to use "a formal language of nested delimiters" that could be...

Previously, we've looked at code generation in both Rails and Thrift. But unlike Thrift, the code generated by Rails is meant to be changed. Any change is fine, so long as it's not too surprising; the only limit is our judgement. Rails, then, doesn't fit the limb-metaphor. Our explanation will not always end with the model. Even so, the model...

In their paper on Evolvability, Marc Kirschner and John Gerhart discuss the separation of concerns within our genetic code. They pay special attention to limbs: The limb is a complex structure with precisely placed bone, cartilage, muscle, nerves, and vascular elements, and one might think it is difficult for such a structure to change in...

In their paper on Evolvability, Marc Kirschner and John Gerhart discuss the separation of concerns within our genetic code. They pay special attention to limbs: The limb is a complex structure with precisely placed bone, cartilage, muscle, nerves, and vascular elements, and one might think it is difficult for such a structure to change in...

Previously, we explored how coupling and cohesion are not separable concepts. When our software is cohesive, everything fits. Each part is shaped by its relationships. Together, they comprise an undirected graph, which we will call a structure. Each structure is an amplifier; by explaining one vertex, we begin to explain the others. Often, these...

complexity The sum of every explanation. Weighted heavily towards future explanations. Measured in bits, but only relative to your audience's expectations. See also: a brief introduction coupling The degree to which two things tend to be explained together. Sometimes it helps, and sometimes it doesn't. See also: coupling as co-explanation...

Previously, I provided a brief introduction to this newsletter, and then analyzed the structure of explanations in software development. For many in the software industry, "coupling" is a dirty word. This dates back to a 1974 paper entitled Structured Design1, which asserted that the goal of software design was to minimize coupling and maximize...

Previously, I provided a brief introduction to the ideas that will be covered in this newsletter. Software development can be reduced to a single, iterative step. Almost everything we do in the course of a day — the pull requests, the meetings, the whiteboard diagrams, the hallway conversations — is an explanation. Our job is to explain, over and...

As software designers, our goal is to reduce complexity. We want our software to be easier to understand, and easier to change. These are not distinct concerns. For our software to be understood or changed, it must be explained; we must tell a story about what our software is, and what it's expected to become. When understanding software, we tell...