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.

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!

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

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.