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.

https://pkgstats.archlinux.de/fun

That sounds like spam. I’ll report just in case.

That’s pretty much what I’d like. So no idea if there are any clients with that functionality?

AI-made aliens of all kinds and sizes. I wouldn’t mind recreating the cantina scene from the original Star Wars trilogy by walking into a bar and, in real-time, using deepfake technology to transform everyone into a random alien species from Star Wars.

You must have made that up, there’s not even a definition on Urban Dictionary.

Also, is this a hobby or a kink, because it reminds me of kinks like chastity, plapping and such.

Wow, finally I figured that out, thank you.

deleted by creator

The locations, free falling and such.

Extreme Ironing

No? It doesn’t seem to be a use case they target.

The problem is that making a repository private makes users think their data can’t be seen so they may upload that kind of information.

If you want to use git to store sensitive data, you should encrypt it before committing / pushing it.

I’ll look into that.

Wow, I bet they don’t even bother warning their sexual partners about it. I wish I had never learned that.

This is only the second time I’ve heard about it. The first time, someone was talking about worm composting (vermicomposting), which uses worms to convert organic waste into nutrient-rich compost.

The circular symbol on black background looks like the many ChatGPT clones.

You are right, but gooning is a kink rather than a hobby as well and you didn’t mention it to the poster of the most voted comment.

pick up artistry, penis enhancement, prejac training

Yeah, some people share their entire drives, so the people who share system files are likely to have their private files there as well.

That’s just a modern term for jerking off, I don’t think it’s niche or weird, I just don’t get why it’s gotten so popular calling it that way.

I stalk random people on the Internet

I like watching people on the internet. 15y ago, I was using Shareaza, Kazaa, Emule as my music sources. For those who aren’t familiar with those software: it’s p2p file download. You install Shareaza on your computer, and give access to specific folder to the Shareaza network. Anyone using Shareaza can then download the files located on your shared folder. But, in the mid 00’, even more than today, people weren’t that tech savy and what happened, way too often, was that a user would give access to the “My Documents” folder or even worse, their whole computer. I was looking for those thoses and I was reading their MSN messenger history, looking at their pictures, their resume, their schoolwork… I was really enjoying learning everything about their life through their My Documents folder.

Fast forward to 2018. All those p2p software disappeared. But I found an alternative: 4shared. 4shared allows you to upload pictures and share them (like img). When you download the app, you can setup the app to automatically upload all your pictures (from your phone). But a lot of users don’t know that, and they end up with all they smartphone pictures on the net, with a public settings. I enjoy going to 4shared, looking for those non savy users, and learn everything about their lifes.

And I don’t even need that. I have hobbies, friends, I don’t have issues meeting women or people, but I like stalking on those strangers on 4shared.

source