Summary of A Philosophy of Software Design by John Ousterhout Source: danlebrero.com

These are notes by Daniel Lebrero Berna on John Ousterhout’s A Philosophy of Software Design.

Some advice in the book goes against the current software dogma. The current dogma is the result of previous pains, but has now been taken to the extreme, causing new pains.

What the author solves with “Comment-First Development,” others solve with Test-Driven Development. The excuses for not writing comments mirror those for not writing tests.

---

Key Insights

• It’s easier to see design problems in someone else’s code than your own.
• Total complexity = Σ(complexity of part × time spent on that part).
• Goal of good design: make the system obvious.
• Complexity accumulates incrementally, making it hard to remove. Adopt a “zero tolerance” philosophy.
• Better modules: interface much simpler than implementation (Deep modules).
• Design modules around required knowledge, not task order.
• Adjacent layers with similar abstractions are a red flag.
• Prioritize simple interfaces over simple implementations.
• Each method should do one thing and do it completely.
• Long methods are fine if the signature is simple and the code easy to read.
• Difficulty naming a method may indicate unclear design.
• Comments should add precision or intuition.
• If you aren’t improving the design when changing code, you’re probably making it worse.
• Comments belong in the code, not commit logs.
• Poor designers spend most of their time chasing bugs in brittle code.

---

Preface

• The most fundamental problem in computer science is problem decomposition.
• The book is an opinion piece.
• The goal: reduce complexity.

1. Introduction (It’s All About Complexity)

• Fight complexity by simplifying and encapsulating it in modules.
• Software design is never finished.
• Design flaws are easier to see in others’ code.

2. The Nature of Complexity

• Complexity = what makes code hard to understand or modify.
• Total complexity depends on time spent in each part.
• Complexity is more obvious to readers than writers.
• Symptoms: change amplification, cognitive load, unknown unknowns.
• Causes: dependencies, obscurity.
• Complexity accumulates incrementally; remove it aggressively.

3. Working Code Isn’t Enough

• Distinguish tactical (short-term) from strategic (long-term) programming.
• The “tactical tornado” writes lots of code fast but increases complexity.

4. Modules Should Be Deep

• A module = interface + implementation.
• Deep modules have simple interfaces, complex implementations.
• Interface = what clients must know (formal + informal).
• Avoid “classitis”: too many small classes increase system complexity.
• Interfaces should make the common case simple.

5. Information Hiding (and Leakage)

• Information hiding is key to deep modules.
• Avoid temporal decomposition (ordering-based design).
• Larger classes can improve information hiding.

6. General-Purpose Modules Are Deeper

• Make modules somewhat general-purpose.

• Implementation fits current needs; interface supports future reuse.

• Questions to balance generality:

  • What is the simplest interface covering current needs?
  • How many times will it be used?
  • Is the API simple for current use? If not, it’s too general.

7. Different Layer, Different Abstraction

• Adjacent layers with similar abstractions are a red flag.
• Pass-through methods and variables add no value.
• Fix pass-throughs by grouping related data or using shared/context objects.

8. Pull Complexity Downwards

• Prefer simple interfaces over simple implementations.
• Push complexity into lower layers.
• Avoid configuration parameters; compute reasonable defaults automatically.

9. Better Together or Better Apart?

• Combine elements when they:

  • Share information.
  • Are used together.
  • Overlap conceptually.
  • Simplify interfaces or eliminate duplication.

• Developers often split methods too much.

• Methods can be long if they are cohesive and clear.

• Red flag: one component requires understanding another’s implementation.

10. Define Errors Out of Existence

• Exception handling increases complexity.

• Reduce exception points by:

  • Designing APIs that eliminate exceptional cases.
  • Handling exceptions at low levels.
  • Aggregating exceptions into a common type.
  • Crashing when appropriate.

11. Design It Twice

• Explore at least two radically different designs before choosing.

12. Why Write Comments? The Four Excuses

• Writing comments improves design and can be enjoyable.

• Excuses:

  • “Good code is self-documenting.” False.
  • “No time to write comments.” It’s an investment.
  • “Comments get outdated.” Update them.
  • “Comments are worthless.” Learn to write better ones.

13. Comments Should Describe Things That Aren’t Obvious

• Comments should add precision and intuition.
• Document both interface and implementation.

14. Choosing Names

• Names should be precise and consistent.
• If naming is hard, the design likely isn’t clean.

15. Write the Comment First

• Like TDD, comment-first helps design, pacing, and clarity.

16. Modifying Existing Code

• Always improve design when changing code.
• Comments belong in code, not commit logs.

17. Consistency

• Don’t “improve” existing conventions without strong reason.

19. Software Trends

• Agile and TDD often promote tactical programming.

20. Designing for Performance

• Simpler code tends to be faster.
• Design around the critical path.

21. Conclusion

• Poor designers spend their time debugging brittle systems.

Summary of Clean Code by Robert C. Martin
Source: gist.github.com/wojteklu

Code is clean if it can be understood easily – by everyone on the team. Clean code can be read and enhanced by a developer other than its original author. With understandability comes readability, changeability, extensibility, and maintainability.

---

General rules

1. Follow standard conventions.
2. Keep it simple stupid. Simpler is always better. Reduce complexity as much as possible.
3. Boy scout rule. Leave the campground cleaner than you found it.
4. Always find root cause. Always look for the root cause of a problem.

Design rules

1. Keep configurable data at high levels.
2. Prefer polymorphism to if/else or switch/case.
3. Separate multi-threading code.
4. Prevent over-configurability.
5. Use dependency injection.
6. Follow Law of Demeter. A class should know only its direct dependencies.

Understandability tips

1. Be consistent. If you do something a certain way, do all similar things in the same way.
2. Use explanatory variables.
3. Encapsulate boundary conditions. Boundary conditions are hard to keep track of. Put the processing for them in one place.
4. Prefer dedicated value objects to primitive type.
5. Avoid logical dependency. Don’t write methods which work correctly depending on something else in the same class.
6. Avoid negative conditionals.

Names rules

1. Choose descriptive and unambiguous names.
2. Make meaningful distinction.
3. Use pronounceable names.
4. Use searchable names.
5. Replace magic numbers with named constants.
6. Avoid encodings. Don’t append prefixes or type information.

Functions rules

1. Small.
2. Do one thing.
3. Use descriptive names.
4. Prefer fewer arguments.
5. Have no side effects.
6. Don’t use flag arguments. Split method into several independent methods that can be called from the client without the flag.

Comments rules

1. Always try to explain yourself in code.
2. Don’t be redundant.
3. Don’t add obvious noise.
4. Don’t use closing brace comments.
5. Don’t comment out code. Just remove.
6. Use as explanation of intent.
7. Use as clarification of code.
8. Use as warning of consequences.

Source code structure

1. Separate concepts vertically.
2. Related code should appear vertically dense.
3. Declare variables close to their usage.
4. Dependent functions should be close.
5. Similar functions should be close.
6. Place functions in the downward direction.
7. Keep lines short.
8. Don’t use horizontal alignment.
9. Use white space to associate related things and disassociate weakly related.
10. Don’t break indentation.

Objects and data structures

1. Hide internal structure.
2. Prefer data structures.
3. Avoid hybrids structures (half object and half data).
4. Should be small.
5. Do one thing.
6. Small number of instance variables.
7. Base class should know nothing about their derivatives.
8. Better to have many functions than to pass some code into a function to select a behavior.
9. Prefer non-static methods to static methods.

Tests

1. One assert per test.
2. Readable.
3. Fast.
4. Independent.
5. Repeatable.

Code smells

1. Rigidity. The software is difficult to change. A small change causes a cascade of subsequent changes.
2. Fragility. The software breaks in many places due to a single change.
3. Immobility. You cannot reuse parts of the code in other projects because of involved risks and high effort.
4. Needless Complexity.
5. Needless Repetition.
6. Opacity. The code is hard to understand.

One principle I try to apply (when possible) comes from when I learned Haskell. Try to keep the low-level logical computations of your program pure, stateless functions. If their inputs are the same, they should always yield the same result. Then pass the results up to the higher level and perform your stateful transformations there.

An example would be: do I/O at the high level (file, network, database I/O), and only do very simple data transformations at these levels (avoid it altogether if possible). Then do the majority of the computational logic in lower level, modular components that have no external side effects. Also, pass all the data around using read-only records (example: Python dataclasses with frozen=True) so you know that nothing is being mutated between these modules.

This boundary generally makes it easier to test computational logic separately from stateful logic. It doesn’t work all the time, but it’s very helpful in making it easier to understand programs when you can structure programs this way.

Zen of python (PEP 20):

Beautiful is better than ugly. Explicit is better than implicit. Simple is better than complex. Complex is better than complicated. Flat is better than nested. Sparse is better than dense. Readability counts. Special cases aren’t special enough to break the rules. Although practicality beats purity. Errors should never pass silently. Unless explicitly silenced. In the face of ambiguity, refuse the temptation to guess. There should be one-- and preferably only one --obvious way to do it. Although that way may not be obvious at first unless you’re Dutch. Now is better than never. Although never is often better than right now. If the implementation is hard to explain, it’s a bad idea. If the implementation is easy to explain, it may be a good idea. Namespaces are one honking great idea – let’s do more of those!

Encapsulation.

Any time i even think I need inheritance, I immediately change it for encapsulation. I’ve never regretted this.

Not clean code - uncle Bob is a hack.

KISS YAGNI DRY in that order.

Think about coupling and cohesion. Don’t tie things together by making them share code that coincidentally is similar but isn’t made for the same purpose.

Don’t abstract things until you have at least 2 (preferably 3) examples of what you’re trying to abstract. If you try to guess at the requirements of the 2nd or 3rd thing you’ll probably be wrong and have to undo or live with mistakes.

When you so abstract and break things down, optimize for reading. This includes maximizing loading the code into your head. Things that make that hard are unnecessary indirections (like uncle Bob tells you to do) and shared state (like uncle Bob tells you to do).

Pure functions (meaning they take inputs and remit outputs without any side effects such as setting shared state) are the platonic ideal. Anything written not as a pure function should have a reason (there are tons of valid reasons, but it’s a good mental anchor)

I should really read the Ousterhout book. It would be great if I could just point people at something, and it sounded decent from that discussion between him and Bob I saw the other day

Edit: I don’t agree with everything in here but it’s pretty great https://grugbrain.dev/

• Low coupling, high cohesion
• Sometimes it’s better to use a less optimized solution for clarity or simplicity
• A simple solution is usually better than a “clever” one
• Allot time for refactoring during development, don’t assume it will be done later (spoiler: it won’t)

I write my code for future maintainers. I optimize for clarity, testability, and readability.

I’ve become a huge fan of dependency injection. That does not mean I like DI frameworks (Guice). I tend to do it manually with regular code.

When I maintain code and I sit there wondering what it actually does, I write a unit test for it right then and there

And so on

When I explore or consider alternatives, I don’t think of or ask myself about design principles, but consider and weigh what could and would make sense where I am.

More than principles, the guiding goal is Maintainability - Readability, Graspability, Consistency, Correctness, Robustness. Weighted against constraints.

I guess separation of concerns is a big one I use implicitly. Like many others.

I’d say “Separation of Responsibilities” is probably my #1. Others here have mentioned that you shouldn’t code for future contingencies, and that’s true, but a solid baseline of Separation of Responsibilities means you’re setting yourself up for future refactors without having to anticipate and plan for them all now. I.E. if your application already has clear barriers between different small components, it’s a lot easier to modify just one or two of them in the future. For me, those barriers mean horizontal layers (I.E. data-storage, data-access, business logic, user-interfacing) and vertical slicing (I.E. features and/or business domains).

Next, I’ll say “Self-Documenting Code”. That is, you should be able to intuit what most code does by looking at how it’s named and organized (ties into separation of responsibilities from above). That’s not to say that you should follow Clean Code. That takes the idea WAY too far: a method or class that has only one call site is a method or class that you should roll into that call site, unless it’s a separation of responsibility thing. That’s also not to say that you should never document or comment, just that those things should provide context that the code doesn’t, for things like design intent or non-obvious pitfalls, or context about how different pieces are supposed to fit together. They should not describe structure or basic function, those are things that the code itself should do.

I’ll also drop in “Human Readability”. It’s a classic piece of wisdom that code is easier to write than it is to read. Even of you’re only coding for yourself, if you want ANY amount of maintainability in your code, you have to write it with the intent that a human is gonna need to read and understand it, someday. Of course, that’s arguably what I already said with both of the above points, but for this one, what I really mean is formatting. There’s a REASON most languages ignore most or all whitespace: it’s not that it’s not important, it’s BECAUSE it’s important to humans that languages allow for it, even when machines don’t need it. Don’t optimize it away, and don’t give control over when and where to use it to a machine. Machines don’t read, humans do. I.E. don’t use linters. It’s a fool’s errand to try and describe what’s best for human readability, in all scenarios, within a set of machine-enforceable rules.

“Implement now, Optimize later” is a good one, as well. And in particular, optimize when you have data that proves you need it. I’m not saying you should intentionally choose inefficient implementations just because they’re simpler, but if they’re DRASTICALLY simpler… like, is it really worth writing extra code to dump an array into a hashtable in order to do repeated lookups from it, if you’re never gonna have more than 20 items in that array at a time? Even if you think you can predict where your hot paths are gonna be, you’re still better off just implementing them with the KISS principal, until after you have a minimum viable product, cause by then you’ll probably have tests to support you doing optimizations wolithout breaking anything.

I’ll also go with “Don’t be afraid to write code”, or alternatively “Nobody likes magic”. If I’m working on a chunk of code, I should be able to trace exactly how it gets called, all the way up to the program’s entry point. Conversely, if I have an interface into a program that I know is getting called (like, say, an API endpoint) I should be able to track down the code it corresponds to bu starting at the entry point and working my way down. None of this “Well, this framework we’re using automatically looks up every function in the application that matches a certain naming pattern and figures out the path to map it to during startup.” If you’re able to write 30 lines of code to implement this endpoint, you can write one more line of code that explicitly registers it to the framework and defines its path. Being able to definitively search for every reference to a piece of code is CRITICAL to refactoring. Magic that introduces runtime-only references is a disaster waiting to happen.

As an honorable mention: it’s not really software design, but it’s somethign I’ve had to hammer into co-workers and tutorees, many many times, when it comes to debugging: “Don’t work around a problem. Work the problem.”. It boggles my mind how many times I’ve been able to fix other people’s issues by being the first one to read the error logs, or look at a stack trace, or (my favorite) read the error message from the compiler.

“Hey, I’m getting an error ‘Object reference not set to an instance of an object’. I’ve tried making sure the user is logged in and has a valid session.”

“Well, that’s probably because you have an object reference that’s not sent to an instance of an object. Is the object reference that’s not set related to the user session?”

“No, it’s a ServiceOrder object that I’m trying to call .Save() on.”

“Why are you looking at the user session then? Is the service order loaded from there?”

“No, it’s coming from a database query.”

“Is the database query returning the correct data?”

“I don’t know, I haven’t run it.”

I’ve seen people dance around an issue for hours, by just guessing about things that may or may not be related, instead of just taking a few minutes to TRACE the problem from its effect backwards to its cause. Or because they never actually IDENTIFIED the problem, so they spent hours tracing and troubleshooting, but for the wrong thing.

Idempotence / self-healing: the system should be built in such a way that it tries to reach the correct end state, even if the current state is wrong. For instance, every time our system gets an update, it will re-evaluate the calculation from first principles, instead of doing a diff based on what was there before. This prevents bad data from snowballing and becoming a catastrophe.

Giving yourself knobs to twiddle in production: at work we have ways of triggering functionality in the system on request. Basically calling a method directly on the running process. This is so, so useful in prod issues, especially when combined with the above. We can basically tell the system “reprocess this action/command/message” at any time and it will do it again from first principles.

Debugging: I always first try and find a way to replicate it quickly. Then, I try and simplify it one tiny step at a time until it’s small enough I can understand in one go. I never combine multiple steps per re-run and always verify whether the bug is there or not at every single stage. This can be quite a slow approach but it also means I am always making progress towards finding the answer, instead of coming up with theories which are often wrong, and getting lost in the process.

Destroy abstractions

The reality is, if you have an abstraction layer and one implementation of it, you dont need that abstraction layer

People will complain, “oh but think about the refactor if we have to change vendors/etc” but i have yet to ever switch vendors/api/etc and not had to completely rethink the abstraction layer

Just get rid of it, it will be easier, less code, more precise, and in the long run you’ll cargo cult less

Just write the code for the things you have, and if things change, yup then things will change - to anticipate future changes and upfront the work for the unknown only to then have to make more changes once those real changes eventually arrive and dont match your old predictions is just more work and more confusion

Don’t design for having a nice codebase today, design for having a clean codebase after 3 months of Devs copy pasting one bit of code then tweaking it to do what they need or adding more fields to existing concepts.

This generally means it’s best to have one pattern for a given thing, rather than having several patterns you pick based on context, the later runs into problems:

• Someone copy/pasted pattern A for a pattern B context
• Enough stuff changes in a pattern A implementation that it would now be better as a patter B thing.

A second consideration for this is that if there are a group of classes/files/whatever that regularly needs to be copied they should live together. If there are different sections of the code that needs to be edited when creating a new resource, they should be kept in one place and kept small-ish.

Most of this comes from accepting the way people tend to work and from the perspective that software is a living evolving process and only regarding a snapshot of it misses vital information.

Cut the problem into tiny pieces, then group it back together with nice clean connections

Code in nice straight lines. Like good cable management - behaviors should flow from cause to effect, and as much as possible should flow through the main channels

Decide how you organize things, and stick to it. When you see code you don’t remember writing, you should be able to say “if I were me, how would I do this?” and immediately know the correct answer

Single responsibility. I deplore my backend developers who think that just because you’re mauling a single (Java) stream for an extended operation, it’s ok to write a single wall-of-text, 5 lines long, 160 characters wide. Use fucking line breaks, for fuck’s sake!