Philosophy of Software Design - Book Club

There are a lot of engineering books. They often have lots and lots of words, but only one or two good chapters. Which isn’t that much fun.

The Philosophy of Software Design by John Osterhaut bucks that trend, and is packed with a lot of meaning in very few and consise pages. This makes it a great book club book. The topics involved can help a lot alignment around the philosophical mindset behind coding. It’s helped me with long running teams where they’d drifted in purpose, and on brand new teams where we were all getting to know each other. If you’re looking for an overview, there’s a youtube talk that’s ~1hr¹, and at a much lower fidelity, I put together some slides about it a while back.

The book covers 16 core concepts², and they break up into nice 20-ish page sections for weekly discussions. In total this low-effort high-reward book club can be done in 5 weeks.

Book Club Goals:

• Meaningful conversations
• Not too much reading each week
• Turn reading into adjustments to team processes/values

In the back of the book, there’s a “Summary of Design Principles” The goal is to break up the sessions to contain a few of those for discussion. When meeting to discuss walk through each chapter and relate it to current work, projects, or ongoing PRs. All the tradeoffs we make, even in little things, are relevant for discussion.

Tactically

• The reading should take about 45 min each week, it’s a small book
• Discussion should take about an hour
• Keep a running doc or slack channel for notes and thoughts as you go
• If you’re running the book club, try and prepare with some relevant examples from the code ya’ll work with

Week 1: Chapters 1-4

Principles Covered:

• Complexity is incremental, you have to sweat the small stuff
• Working code isn’t enough
• Make continued small investments to improve system design
• Modules should be deep
• Interfaces should be designed to make the most common usage as simple as possible

Week 2: Chapters 5-9

Principles Covered:

• It’s more important for a module to have a simple interface than a simple implementation
• General purpose modules are deeper
• Separate general purpose and special purpose code
• Different layers should have different abstractions
• Pull complexity downward

Week 3 Chapters 10-13

Principles Covered:

• Define Errors out of existence
• Design it twice
• Comments should describe things that are not obvious from the code

Week 4: Chapters 14-16

Principles Covered:

• None called out specifically, but there’s a bunch in here

Week 5: Chapters 17-22

Principles Covered:

• Software should be designed for ease of reading, not ease of writing
• The increments of software development should be abstractions not features
• Separate what matters from what doesn’t matter and emphasize the things that matter

What next?

The rest is up to you.

Take a couple of the ideas that resonated most with the group and change a bit of process to encourage their use. Start to refer to these principles into code review. Use them to design the scope and shape of your pull requests. Let them do the work of representing a complex idea as it relates to complex code. Keep the ideas alive, and they’ll eventually flourish.

---

1. Watch it in doublespeed ↩︎

2. 1. Complexity is incremental: you have to sweat the small stuff
   2. Working code isn’t enough
   3. Make continual small investments to improve system design
   4. Modules should be deep
   5. Interfaces should be designed to make the most common usage as simple as possible
   6. It’s more important for a module to have a simple interface than a simple implementation
   7. General-purpose modules are deeper
   8. Separate general-purpose and special-purpose code
   9. Different layers should have different abstractions
   10. Pull complexity downward
   11. Define errors out of existence
   12. Design it twice
   13. Comments should describe things that are not obvious from the code
   14. Software should be designed for ease of reading, not ease of writing
   15. The increments of software development should be abstractions, not features
   16. Separate what matters from what doesn’t matter and emphasize the things that matter
    ↩︎