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.

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

I checked some of the forums in the link (https://nodebb.fediverse.observer/list) you posted, but it’s hard to tell what most of those NodeBB instances are actually for: many lack descriptions and the forum names don’t say much. I would have to read a few posts in each forum to figure out what each one is for. I found a literature forum but it only has three posts, I don’t want to make an account just to shout into the void, so I’m trying to post to it from Lemmy.

I tried posting to the literature community I found via Lemmy but the post never showed up on the NodeBB instance. I used Lemmy’s search with the target community URL (https://community.darkscribes.com/category/2/general-discussion), it found the community, and I created a post from Lemmy (https://lemmy.dbzer0.com/post/54997372). I can see the post on Lemmy but not on the target NodeBB instance. Any idea why that might be or how to get Lemmy posts to appear on federated NodeBB forums?

I think moderating tags is the same as moderating any other content. If there’s a brigade, you can revert all tag changes made by the brigading users the same way you remove content posted by a user when banning them. That said, the moderation system could be improved. Reddit-style moderation is one of the biggest jokes on the internet.

You don’t seem to get my point. For a platform to let me reliably filter a whole topic, the majority of posts need to be tagged with that topic first. Reddit/Facebook don’t do that, they have communities and loose categories, not consistent topic tags across all posts. Twitter only partially does it with hashtags, and hashtags are neither comprehensive nor applied consistently. I’m talking about platform-level, booru-style or collaborative tagging so blocking a tag actually removes the tagged content without me having to unsubscribe from dozens of communities or build giant keyword lists.

Honestly, I wouldn’t recommend adding the feature to mark comments as solutions. Websites like StackOverflow often have many answers that aren’t the best marked as solutions, and I believe platforms like Codidact have learned from those mistakes.

Reputation is a key factor that motivates people to contribute answers. However, StackOverflow suffers from over-moderation due to the reputation gained from moderating. I’m curious about how Codidact has addressed this issue.

Instead, consider allowing users to mark questions as solved rather than comments. Implementing a voting system similar to Slashdot, where users can categorize responses as helpful, funny, or other descriptors, might be more effective. This way, contributors are incentivized to help, as they can gain reputation points. Then a leaderboard showcasing the most helpful contributors on a weekly or monthly basis could further encourage participation.