5 ms·

A Philosophy of Software Design – Book Summary and Notes

89 points by elvis10ten 4y ago

mandeepj 4y ago
The table of Contents seemed interesting and I was getting ready to buy the book until I discovered - the author has reserved between 1/3 and 1/4 of the book for chapters about writing comments.
- Jtsummers 4y ago
  ~1/7 of the book by page count (about 30 pages if you tally the chapter lengths of nearly 200 pages), three chapters of twenty-two are dedicated to that topic (so not even 1/7th of the chapters). That seems reasonable since it's meant to be a broad book regarding software design and development. At least one page on comments is actually an answer to part of Clean Code, which is also relevant as the two books are in, roughly, the same subcategory of books on programming.
  - mandeepj 4y ago
    > ~1/7 of the book by page count (about 30 pages if you tally the chapter lengths of nearly 200 pages), Comments chapters start from Page #91 to 142, totals to 52. Total pages - 175; not counting index and summary pages. 1/4 of 175 = 43.75 1/3 of 175 = 58.33
    - Jtsummers 4y ago
      No, it doesn't. There are three chapters in that span that are on comments, but not all the chapters in that span are on comments. One is on naming things (Ch 14) and one is on modifying existing code (Ch 16). There are three chapters per the TOC that cover comments explicitly (versus where it may be touched on in other chapters): Ch 12 (pages 95-99), Ch 13 (101-120) and Ch 15 (131-135). That's a whopping 30 pages.
- lolc 4y ago
  You seem to consider it a negative to spend time on comments. Why?
  - mandeepj 4y ago
    > You seem to consider it a negative to spend time on comments. Why? Not just me. I've heard, read - here at HN, in the industry, blogs, co-workers, other books - the code should be self-explanatory. If it needs comments to explain then either the code author can't write good code or they are overly complicating it. Besides that, over time, comments get obsolete. We've to fight to get capacity to address tech debt. I don't see that time getting used in refreshing the comments
    - layer8 4y ago
      It’s a vocal but minority opinion, certainly a highly controversial one. As an easy example, it’s pretty difficult for code to self-document why a particular implementation approach was chosen. The book actually addresses the points you note.
    - lolc 4y ago
      Short vars, long vars. Golfer, extender. Globalist and miniscoper. Class-splitter and method-lumper. Abstract composer and dead-on implementer. Typers, Dicters and Tuplers. I think I've seen them all. But so far I have not worked with a single person who'd not value a well-placed comment. Can you point me to a codebase that does not use comments, as a model of how that looks in practice?
      - layer8 4y ago
        I believe I understand most of those, but what’s a dead-on implementer?
        lolc 4y ago
        Not looking beyond the next line to solve a task.
ahmadmijot 4y ago
Not really about your note summaray but neat. I really want to make a digital garden like yours with notes and all. I read plenty of books and articles but I'm helpless when to documenting my findings.
Jtsummers 4y ago
Apparently there's a second edition out as of last year (2021). Ousterhout has a page about it describing the difference between the two editions and a download for those (like me) who have read the first and don't necessarily want to purchase another copy that's not totally different. One new chapter, one reworked chapter, and two new sections comparing his philosophy against Clean Code. https://web.stanford.edu/~ouster/cgi-bin/book.php https://web.stanford.edu/~ouster/cgi-bin/book.php
- elvis10ten 4y ago
  Thanks. I will read this and update the summary. I have updated the book link to point to the second edition.
- doodpants 4y ago
  Thanks for this. I bought and read the first edition last year, and the second edition was published right while I was in the middle of reading it! (Which I didn't discover until a month after I had finished reading.)
- victorabarros 4y ago
  I didn't know this new edition. Thank you, now I have one more reason to re-read this book. It's amazing.
deltaonefour 4y ago
>Programmers aren’t bound by practical limitations such as laws of physics, they are bound by their limited ability to understand the systems they create. First line is already wrong. I mean I get the meaning but this is not technically true. Computing is bounded by the laws of physics. We have bottlenecks and limitations everywhere this is entirely due to physics. It influences even the style of programming. There is much more parallelism in programming today due very much to physical limitations in raw speed.
- troelsSteegin 4y ago
  It's that the active constraint is understanding.
- stnmtn 4y ago
  A better way to interpret "constraint" in this is as the "limiting factor."
- elvis10ten 4y ago
  Other comments have already responded to this. I will just add two excerpts that came to my mind when I read this in the book. > The constraints imposed in building large software systems are the limitations of the human mind; opposed to the physical systems' constraints in other kinds of engineering. - MIT 6.001 Structure and Interpretation: https://youtube.com/playlist?list=PLE18841CABEA24090 https://youtube.com/playlist?list=PLE18841CABEA24090 > The programmer, like the poet, works only slightly removed from pure thought-stuff. He builds castles in the air, from air, creating by exertion of the imagination. Few media of creation are so flexible, so easy to polish and rework, so readily capable of realizing grand conceptual structures. Yet the program construct, unlike the poet's words, is real in the sense that it moves and works, producing visible outputs separate from the construct itself. It prints results, draws pictures, produces sounds, moves arms. - Mythical man month
  - lbriner 4y ago
    The Mythical Man Month might be an object of worship but it was written in 1975 at a time when software engineering was VERY different than today. Most of what today's developers do is not close to castles in the air and much more like building generic office blocks on the ground. Of course, some people have to solve novel problems but 99% of us don't, we just solve the same problems again and again.
deleted 4y ago
[deleted]
seclorum_wien 4y ago
It is quite extraordinary that such a treatise would not have an entire section on "What is a User?", and really very weird to me that the primacy of the user over the developer, in terms of making the thing useful, is ignored.
- layer8 4y ago
  The book is about the inner design of software (how you implement your product), not about product design (what the user sees).
knowmad 4y ago
Great notes! I recently read Philosophy of Software Design, but decided not to take notes on it because I wanted to finish it in a reasonable time period. I'm currently a few chapters into a few other books which I chose to take notes on, but it's very slow going and my desire to read those books has decreased because it feels like a slog. How do you combat the desire to note every little detail (how do you decide what's important)? Also, do you take notes directly in a text editor, or do you take handwritten notes and then transcribe them later?
- elvis10ten 4y ago
  > How do you combat the desire to note every little detail (how do you decide what's important)? I try to focus on the general idea of each section in a book. > Also, do you take notes directly in a text editor Yes, in markdown.
- rramadass 4y ago
  https://en.wikipedia.org/wiki/Critical_pr%C3%A9cis https://en.wikipedia.org/wiki/Critical_pr%C3%A9cis https://www.businessstudynotes.com/personal-skills/precis-writing/ https://www.businessstudynotes.com/personal-skills/precis-wr... https://www.gutenberg.org/ebooks/53680 https://www.gutenberg.org/ebooks/53680 Take Notes by hand using Paper/Pen/Pencil, use text, diagrams whatever you need to enhance your comprehension; Transcribe later to Computer, if needed.
deleted 4y ago
[deleted]
nonrandomstring 4y ago
I'm getting delicious hints of Brooks, Gall, Deming, and Meadows in this mix. Just reading through the TOC it feels like he's building the premises for a knock-down argument against code mono-cultures built by giant teams and delivered JIT on the meanest budget by corrupt monopolies. But then of course he is. As Ian Sommerville more or less said it the other day, we've got the philosophies, the textbooks, the smart people, the pragmatism, and the need, so why don't we get to build the quality of software we know in our hearts we can make and deserve? Is what we call "infrastructure" today a stagnation by which Capitalism ultimately eats its own means of innovation?
epage 4y ago
One of the reasons I appreciate this book so much, even if I disagree with parts, is the author's humble approach starting with the title, with both "a" and "philosophy". Throughout the content I also felt like he invited me to disagree with him. This made me like it was more of a conversation of trade offs rather than an argument on who is right.
layer8 4y ago
I like the book a lot, however one flaw it has is that it provides too few concrete examples to illustrate what it is talking about, and thus often remains in the abstract. You basically already have to have the experience to recognize and remember the situations it’s talking about, and then nod along when your experience matches the author’s.

89 points by elvis10ten 4y ago

The table of Contents seemed interesting and I was getting ready to buy the book until I discovered - the author has reserved between 1/3 and 1/4 of the book for chapters about writing comments.

Jtsummers 4y ago
~1/7 of the book by page count (about 30 pages if you tally the chapter lengths of nearly 200 pages), three chapters of twenty-two are dedicated to that topic (so not even 1/7th of the chapters). That seems reasonable since it's meant to be a broad book regarding software design and development. At least one page on comments is actually an answer to part of Clean Code, which is also relevant as the two books are in, roughly, the same subcategory of books on programming.
- mandeepj 4y ago
  > ~1/7 of the book by page count (about 30 pages if you tally the chapter lengths of nearly 200 pages), Comments chapters start from Page #91 to 142, totals to 52. Total pages - 175; not counting index and summary pages. 1/4 of 175 = 43.75 1/3 of 175 = 58.33
  - Jtsummers 4y ago
    No, it doesn't. There are three chapters in that span that are on comments, but not all the chapters in that span are on comments. One is on naming things (Ch 14) and one is on modifying existing code (Ch 16). There are three chapters per the TOC that cover comments explicitly (versus where it may be touched on in other chapters): Ch 12 (pages 95-99), Ch 13 (101-120) and Ch 15 (131-135). That's a whopping 30 pages.
lolc 4y ago
You seem to consider it a negative to spend time on comments. Why?
- mandeepj 4y ago
  > You seem to consider it a negative to spend time on comments. Why? Not just me. I've heard, read - here at HN, in the industry, blogs, co-workers, other books - the code should be self-explanatory. If it needs comments to explain then either the code author can't write good code or they are overly complicating it. Besides that, over time, comments get obsolete. We've to fight to get capacity to address tech debt. I don't see that time getting used in refreshing the comments
  - layer8 4y ago
    It’s a vocal but minority opinion, certainly a highly controversial one. As an easy example, it’s pretty difficult for code to self-document why a particular implementation approach was chosen. The book actually addresses the points you note.
  - lolc 4y ago
    Short vars, long vars. Golfer, extender. Globalist and miniscoper. Class-splitter and method-lumper. Abstract composer and dead-on implementer. Typers, Dicters and Tuplers. I think I've seen them all. But so far I have not worked with a single person who'd not value a well-placed comment. Can you point me to a codebase that does not use comments, as a model of how that looks in practice?
    - layer8 4y ago
      I believe I understand most of those, but what’s a dead-on implementer?
      - lolc 4y ago
        Not looking beyond the next line to solve a task.

ahmadmijot 4y ago

Not really about your note summaray but neat. I really want to make a digital garden like yours with notes and all. I read plenty of books and articles but I'm helpless when to documenting my findings.

Jtsummers 4y ago

Apparently there's a second edition out as of last year (2021). Ousterhout has a page about it describing the difference between the two editions and a download for those (like me) who have read the first and don't necessarily want to purchase another copy that's not totally different. One new chapter, one reworked chapter, and two new sections comparing his philosophy against Clean Code. https://web.stanford.edu/~ouster/cgi-bin/book.php https://web.stanford.edu/~ouster/cgi-bin/book.php

elvis10ten 4y ago
Thanks. I will read this and update the summary. I have updated the book link to point to the second edition.
doodpants 4y ago
Thanks for this. I bought and read the first edition last year, and the second edition was published right while I was in the middle of reading it! (Which I didn't discover until a month after I had finished reading.)
victorabarros 4y ago
I didn't know this new edition. Thank you, now I have one more reason to re-read this book. It's amazing.

deltaonefour 4y ago

>Programmers aren’t bound by practical limitations such as laws of physics, they are bound by their limited ability to understand the systems they create. First line is already wrong. I mean I get the meaning but this is not technically true. Computing is bounded by the laws of physics. We have bottlenecks and limitations everywhere this is entirely due to physics. It influences even the style of programming. There is much more parallelism in programming today due very much to physical limitations in raw speed.

troelsSteegin 4y ago
It's that the active constraint is understanding.
stnmtn 4y ago
A better way to interpret "constraint" in this is as the "limiting factor."
elvis10ten 4y ago
Other comments have already responded to this. I will just add two excerpts that came to my mind when I read this in the book. > The constraints imposed in building large software systems are the limitations of the human mind; opposed to the physical systems' constraints in other kinds of engineering. - MIT 6.001 Structure and Interpretation: https://youtube.com/playlist?list=PLE18841CABEA24090 https://youtube.com/playlist?list=PLE18841CABEA24090 > The programmer, like the poet, works only slightly removed from pure thought-stuff. He builds castles in the air, from air, creating by exertion of the imagination. Few media of creation are so flexible, so easy to polish and rework, so readily capable of realizing grand conceptual structures. Yet the program construct, unlike the poet's words, is real in the sense that it moves and works, producing visible outputs separate from the construct itself. It prints results, draws pictures, produces sounds, moves arms. - Mythical man month
- lbriner 4y ago
  The Mythical Man Month might be an object of worship but it was written in 1975 at a time when software engineering was VERY different than today. Most of what today's developers do is not close to castles in the air and much more like building generic office blocks on the ground. Of course, some people have to solve novel problems but 99% of us don't, we just solve the same problems again and again.

deleted 4y ago

[deleted]

seclorum_wien 4y ago

It is quite extraordinary that such a treatise would not have an entire section on "What is a User?", and really very weird to me that the primacy of the user over the developer, in terms of making the thing useful, is ignored.

layer8 4y ago
The book is about the inner design of software (how you implement your product), not about product design (what the user sees).

knowmad 4y ago

Great notes! I recently read Philosophy of Software Design, but decided not to take notes on it because I wanted to finish it in a reasonable time period. I'm currently a few chapters into a few other books which I chose to take notes on, but it's very slow going and my desire to read those books has decreased because it feels like a slog. How do you combat the desire to note every little detail (how do you decide what's important)? Also, do you take notes directly in a text editor, or do you take handwritten notes and then transcribe them later?

elvis10ten 4y ago
> How do you combat the desire to note every little detail (how do you decide what's important)? I try to focus on the general idea of each section in a book. > Also, do you take notes directly in a text editor Yes, in markdown.
rramadass 4y ago
https://en.wikipedia.org/wiki/Critical_pr%C3%A9cis https://en.wikipedia.org/wiki/Critical_pr%C3%A9cis https://www.businessstudynotes.com/personal-skills/precis-writing/ https://www.businessstudynotes.com/personal-skills/precis-wr... https://www.gutenberg.org/ebooks/53680 https://www.gutenberg.org/ebooks/53680 Take Notes by hand using Paper/Pen/Pencil, use text, diagrams whatever you need to enhance your comprehension; Transcribe later to Computer, if needed.

deleted 4y ago

[deleted]

nonrandomstring 4y ago

I'm getting delicious hints of Brooks, Gall, Deming, and Meadows in this mix. Just reading through the TOC it feels like he's building the premises for a knock-down argument against code mono-cultures built by giant teams and delivered JIT on the meanest budget by corrupt monopolies. But then of course he is. As Ian Sommerville more or less said it the other day, we've got the philosophies, the textbooks, the smart people, the pragmatism, and the need, so why don't we get to build the quality of software we know in our hearts we can make and deserve? Is what we call "infrastructure" today a stagnation by which Capitalism ultimately eats its own means of innovation?

epage 4y ago

One of the reasons I appreciate this book so much, even if I disagree with parts, is the author's humble approach starting with the title, with both "a" and "philosophy". Throughout the content I also felt like he invited me to disagree with him. This made me like it was more of a conversation of trade offs rather than an argument on who is right.

layer8 4y ago

I like the book a lot, however one flaw it has is that it provides too few concrete examples to illustrate what it is talking about, and thus often remains in the abstract. You basically already have to have the experience to recognize and remember the situations it’s talking about, and then nod along when your experience matches the author’s.