🧶 A philosophy of Software Design by John K. Ousterhout - Book Notes

January 17, 2026 • 5 min read

Storygraph:A philosophy of Software Design

⛰ What It’s About

“We must find ways to make software simpler.“ This book explores software complexity and ways to reduce it.

🧠 Thoughts

I thought this book would be more philosophical, but instead it goes into concrete ideas and best practices for writing software. While it was a bit of a slow read at times, despite being short, much of the content resonated with me.

What I really liked was that the author openly disagrees with some ideas from Clean Code and backs those disagreements with clear, concrete arguments rather than opinions.

Another thing I appreciated is how the ideas were shared with examples. The book comes across as the author’s genuine wish that we write better, less complex software, not just “clever” software.

What I’ve learned with experience is that, while we may know the theory, in the real world we often don’t have full control or enough time to do things by the book.

I took a bunch of notes on comments in code, probably because I initially learned that these were a bad practice and later realized how useful well-written comments actually are. Seeing AI-generated code add unnecessary comments everywhere makes that difference much clearer.

Overall, this book reinforced something I’ve been slowly learning through experience: writing simple software isn’t about cutting corners or writing less code, it’s about making deliberate design choices that reduce the mental effort required to understand, modify, and maintain the code for everyone who comes after you, including your future self.

✍️ My Top 3 Quotes

• “All programming requires is a creative mind and the ability to organize your thoughts.”

• “Every rule has its exceptions, and every principle has its limits.” - true not just in software, but across many other fields as well.

• 🍰 “Consistency reduces mistakes.”

  
  

📒 Raw highlights / notes

Chapter 1 - Introduction (It’s all about complexity)

“As a software developer, you should always be on the lookout for opportunities to improve the design of the system you are working on.”

Chapter 2 - The nature of complexity

”Complexity is more apparent to readers than writers” → I notice this most with larger PRs. Code makes far more sense to the person who wrote it than to the person reviewing it. This part also makes me think of today’s environment where we write a lot of code with AI. This makes us responsible for the code. It shouldn’t get too complex, we have to read through it, review it and sign off on it.

“Your job as a developer is not just to create code that you can work with easily, but to create code that others can also work with easily.”

“If a software system is hard to understand and modify, then it is complicated; if it is easy to understand and modify, then it’s simple”

Symptoms of complexity

• Simple changes require code modifications in many different places
• Cognitive load: sometimes an approach that requires more lines of code is actually simpler
• Unknown unknowns: when you’re unsure which parts of the code must change

Complexity makes it difficult and risky to modify an existing code base.

Chapter 3 - Working code isn’t enough (Strategic vs tactical programming)

The best engineers care deeply about good design. ⇒ not sure how much this holds, but curious to find out somehow.

If your codebase is a wreck, people will hear about it and might not want to join such a company making recruitment harder.

Chapter 4 - Modules should be deep

Chapter 5 - Information hiding (and leakage)

“When designing modules, focus on the knowledge that’s needed to perform each task, not the order in which the tasks occur” → shares a good example on this

“The best features are the ones you get without even knowing they exist. “

Chapter 6- General-purpose modules are deeper

Questions to ask yourself What is the simplest interface that will cover all my current needs?

Chapter 7 - Different layer, different abstraction

Chapter 8 - Pull Complexity Downwards

“It’s more important for a module to have a simple interface than a simple implementation.”

Chapter 9 - Better together or better apart?

If you find the same pattern of code repeated over and over, see if you can reorganize the code to eliminate the repetition.

A different perspective to Clean Code book

More functions means more interfaces to document and learn. If functions are made too small, they lose their independence, resulting in conjoined functions that must be read and understood together.

❗First make functions deep, then try to make them short enough to be easily read. Don’t sacrifice depth for length.

Chapter 10 - Define errors out of existence

Throwing exceptions is easy, handling them is hard. → if you have been paged during the night for some exception you might relate to this differently 🙈

Chapter 11 - Design it twice

Thinking of all possible ways something can be build helps a lot with writing good software and being aware of trade offs. When writing down a document to be shared with other engineers share possible solutions with pros and cons and then explain why you picked one of them instead of the others.

Chapter 12 - Why write comments? The four excuses

“The idea behind comments is to capture information that was in the mind of the designer but couldn’t be represented in the code’”

A different perspective to Clean Code book “comments are, at best, a necessary evil”

Early in my career, I avoided comments almost entirely because of what I read in Clean Code. I didn’t understand why senior colleagues left comments in the code. Over time, I realized that well-written comments are actually very helpful.

Chapter 13 - Comments should describe things that aren’t obvious from the code

❗Comments should describe things that aren’t obvious from the code. Don’t repeat the code with comments - something I see more and more with AI.

Higher level comments are more difficult to write than lower level comments because you must think of the code in a different way. Ask yourself: What is this code trying to do? What is the simplest thing you can say that explains everything in the code? What is the most important thing about this code?

• Why the code is executed.
• How we get here - when such method gets invoked
• Any tricky aspects that aren’t obvious from the code

“The main goal of implementation comments is to help readers understand what the code is doing.“

If there are tricky aspects to the code that won’t be obvious from reading it, you should document them.

Chapter 14 - Choosing names

Yep, I find naming variables in Go maybe too short and unusual and quite hard especially when not familiar with what some letters stand for. I guess that with experience this gets easier to understand. I also don’t like loooooong names in JavaScript.

Chapter 15 - Write the comments first

Chapter 16 - Modify existing code

Chapter 17 - Consistency

🍰 Consistency reduces mistakes.

Chapter 18 - Code should be obvious

Chapter 19 - Software trends

“One of the risk of agile development is that it can lead to tactical programming” (Tactical programming is a short-term, speed-focused approach to software development) → I feel like this is a more of a it depends situations, sometimes speed is important to make it rather than build something perfect. I know it’s not ideal but business has to keep going we need money to continue building and growing a business.

❤️ test, are great for refactoring → fully agree

“Not every problem can be solved cleanly with an existing design pattern: don’t force a problem into a design pattern when a custom approach will be cleaner.”

Chapter 20 - Designing for Performance

🧠 Before making any changes, measure the system’s existing behaviour.

Making changes based on intuition, you’ll waste time on things that don’t actually improve performance and you’ll probably make the system more complicated in the process.

Complicated code tends to be slow because it does extraneous or redundant work.

Performance isn’t as important for special cases, so you can structure the special-case code for simplicity rather than performance.

Chapter 21 - Decide what matters

Read More:

• ← 🛥️ Feel-Good Productivity: How to Do More of What Matters to You by Ali Abdaal - Book Notes