by Zach Tellman For the past few years, I've been working on a book about software design. Its thesis is fairly simple: > Software development can be reduced to a single, iterative action. 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 over, the meaning of our software: what it is, and what we expect it to become. In this newsletter, I'll be sharing some…
In the previous post , I characterized Ron Jeffries' meandering approach to software design as "a shrug in the face of entropy." Some readers seem to have taken this as a strange, flowery metaphor. It wasn't. In this newsletter, our analytic framework is borrowed from information theory: simplicity is a fitness between content and expectation. When we say software is complex, we mean it's…
In 2006, Ron Jeffries wrote a series of posts describing his attempts to build a Sudoku solver. He began by wrapping a class around a simple datatype for the board — essentially a List[Option[Int]] — and after that, there isn't much to tell. As Peter Seibel puts it: [H]e basically wandered around for the rest of his five blog postings fiddling with the representation, making it more “object…
When we say fiction belongs to a genre, we mean that it builds upon familiar themes and structures. By assigning a genre — a slasher flick, or a comedy of manners, or a murder mystery — we shape the audience's expectations. Genre is a locus ; it makes the rest of the explanation less surprising. And this is the point. People like genre fiction because it's familiar; it can be read easily, or even…
The idea of structure , as used in this newsletter, is nothing new. It was first introduced by Ferdinand de Saussure in 1916, in his enormously influential Course in General Linguistics . In it, Saussure describes language as a graph, and words as vertices. Between these vertices, there are negative edges representing difference, and positive edges representing signification and similarity. To…
When you're responsible for a junior developer, there's an early, crucial milestone: they know when to ask for help. Before this milestone, every task must be carefully curated. Each day of radio silence — be it from embarrassment or enthusiasm — is a cause for concern. Achieving this milestone can be difficult. It requires the developer to intuit the difference between forward motion and…
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. Often, there would be diagrams for the control flow of…
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 continue. There are, however, a wide range of up-metaphors.…
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 mobile app to affect the physical world. This was, at…
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 and BC are not collinear, then a shorter path AC…
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 this newsletter, we are trying to do something similar.…
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 as a question. "Mr. Bicycle Gear, what is your…
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 easily "translated into electrical impulses." This…
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 remains a locus ; for many, it suffices. The only…
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 evolution. 1 Every vertebrate uses the same genes to…
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 vertices have a natural order. There is one vertex…
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 makes things simpler, and sometimes it doesn't. See also: coupling as co-explanation decoupling in depth explanation The core…
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 Design 1 , which asserted that the goal of software design was to minimize coupling and maximize cohesion. The authors defined coupling as…
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 action. 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 over, the meaning of our software: what it is,…
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 that story to ourselves. When changing software,…