Software Design by Example 1: Introduction


In the early 2000s, the University of Toronto asked me to teach an undergraduate course on software architecture. After three runs I told the university to cancel it because of a lack of material: I’d bought a dozen textbooks on the subject, but between them, they devoted a total of less than 30 pages to describing the designs of actual systems.

Frustrated by that, Andy Oram and I persuaded some well-known programmers to contribute chapters to a book called Beautiful Code. Entries described everything from figuring out whether three points are on a line to the ground station software for the Mars Rover, but the breadth that made them fun to read also meant they weren’t particularly useful for teaching.

To fix that, Amy Brown and I (and later Tavish Armstrong and Mike DiBernardo) edited a four-book series called The Architecture of Open Source Applications. In the first two volumes, the creators of fifty open source projects described their systems’ designs; the third book explored the performance of those systems, while contributors to the fourth built scale models of common tools to demonstrate how real ones worked.

These books were closer to what an instructor would need for an undergrad class on software design, but still not quite right. Students wouldn’t be familiar with most of the problem domains, and since each author used the programming language of their choice, most students wouldn’t be able to read most examples. “They’ll get the sense of it” misses the point: discussion and critique of design often hinges on small details, so anything that distracts readers from seeing those details inhibits learning.

So here we are in 2023, and I think I’ve finally created what I wanted twenty years ago. Software Design by Example: A Tool-Based Introduction with JavaScript builds tiny versions of Git, Mocha, the JavaScript VM, and other tools in order to show how they work, but more importantly, to show how experienced programmers think about software design. All the material is available under open licenses, and all royalties from book sales go to support the Red Door Family Shelter in Toronto.

I had three learner personas in mind as I wrote:

I hope to blog about one chapter each week day in January. Feedback is always welcome; while I’ve had to disable comments on this blog (see the explanation in the footer of my site’s home page), you can file issues in in the book’s GitHub repository. I hope you find the material useful, and I’m happy to answer questions by email.

Cover of 'Software Design by Example'

I am grateful to the creators of, Emacs, ESLint, Glosario, GNU Make, LaTeX, Node, NPM, Standard JS, SVG Screenshot, WAVE, and all the other open source tools used in creating these lessons: if we all give a little, we all get a lot. I would also like to thank Darren McElligott, Evan Schultz, and Juanan Pereira for early and ongoing feedback; any errors, omissions, or misunderstandings that remain are entirely my fault.


  1. Each post in this series contains a list of the terms defined in the corresponding chapter. In my experience, a list like this is the quickest way to get a reliable overview of what a lesson is about. You can find the corresponding definitions in the book’s glossary.

  2. I’m translating this book into Python, and adding a few more examples along the way. If you’d like to give early feedback on that material, please reach out.