On "A Philosophy of Software Design"

[John Wilkinson]

Hello Professor Ousterhout,

I hope you are well.

I don't really know how to write a cold email like this, but your book said to write to you at this address, so here it is.

My name is John Mark Wilkinson. I am a software engineer who has worked in the field for a little over fifteen years now.

Firstly, I wanted to say I really appreciate your book. It communicates many ideas that I find helpful and important. I have some minor critiques, but I think I agree with you about probably 95% of the material.

I'll get into the content in a moment; first I want to give you a little background about why I'm writing to you.

How to write maintainable software has been a long time interest of mine, pretty much since I started programming and wrote really atrocious code which I could not make any sense of about two weeks later.

So it's a topic I studied a fair amount, and thought about a lot as I wrote code and experienced other people's code, and eventually I decided to write a book.

That was a few years ago. It took me a while to get started, but I recently finished what is (probably (hopefully)) the final manuscript. I will literally receive the proof copy in about a week.

And then your book came across my radar. I'd heard of it years ago, and had thought I should read it, and then somehow forgot.

So anyway, at the tail end of my journey writing my own book, I finally read yours.

I'm conflicted. So much of what you wrote about is similar to so much of what I put into my book. 

Had I read your book years ago, it may have saved me some effort, as I might not have written mine.

Still, I'm glad I did. They are different enough in form and focus, if not in overall message.

My book has a rather exclusive focus on code, and is rather prescriptive about writing code in certain ways.

Yours is broader, and is more.... philosophical... in nature.

Ok, that's the background of the message. The context.

Here's the things I made note of while reading:

1. Introduction, page 3: "It has been a challenge to find examples that are small enough to include in the book, yet large enough to illustrate the problems with real systems."

I do not think there is any quotation I have related to more.

I could not seem to get around the fact that all examples in a book must be trivial, but no trivial problem can demonstrate why creating "good software" is so important.

2. The crux of the book is about "deep" and "shallow" interfaces. Something I got hung up on a lot was what that really means.

You cover it later in a way that clarified the idea for me, in "Software Trends" page 154: "The more different implementations there are of an interface, the deeper the interface becomes."

Initially, I thought I might disagree because it seemed that "deep" referred to a single interface implementation, with all of the complexity inside that implementation.

But that line clarified it for me. I think the code implications of the design principle were not obvious to me early on.

3. In "Different Layer, Different Abstraction", you talk about "Pass Through Variables", and end by saying "Unfortunately, I haven't found a better solution than contexts." (page 59)

I believe the problem completely disappears simply by not mixing construction graph logic with business logic.

When the two are coupled, pass-through variables are a concern everywhere.

Instead, if the construction graph is created separately from the main business logic of the program, it is trivial to wire in new dependencies or update variables if necessary.

This may raise the objection that doing so pushes a lot of complexity onto the caller. I think this is only true if you design the interface in that way.

For example you could create an utility interface that does all the "normal case" construction graph logic for the caller, and that could be the standard interface.

Internally, if the dependency graph changes, all you need to do is update the interface functions concerned with building that particular part of the construction graph.

In practice, this tends to be only a single place, or perhaps very few.

4. In Chapter 6, in the section "Push specialization upwards (and downwards!)", there is no distinction between which kinds of specializations to push up vs. down.

I realized while reading that section that I haven't thought about it in those terms, but I do this.
Specifically, I push specialization related to concrete behaviors (implementation details, perhaps) down, and I push specialization related to usage up.

So higher-level things decide how they want to use the thing, and lower level things decide how they want to interpret that usage. Or something like that.

5. I really really like the "Design it Twice" principle.

6. In Chapter 15, "Write The Comments First," you talk about using comments as a design tool.

I don't think I agree with this. I mean, sometimes I sort of do this: I'll start by vaguely mapping out my idea via a sequence of comments, and then gradually fill in the details.

But most of the time, I'll rapidly prototype something, and then throw it away due to some behavior or ergonomics that I don't like, and then repeat.

Thinking about the process in terms of your book, I'm searching for the right interface.

Often, I'll add mock out code and use cases that aren't needed yet, and may never be needed, to sort of push on the design, to test its limits.

And then when I discover the right design, where all those pieces sort of just fall into place, I remove all the mocked out garbage, 

do a refactor pass to clean everything up, and during that pass I'll put in the comment with details about the design and how to use it and extend it.

Basically communicate why the design is the way it is.

But I can't do that up front, and I don't think I can do that with comments.
It's easy to comment that something should work some way, it's hard for me to figure out if that really for real makes sense when it comes down to it.

I need code to know that for sure.

But maybe I misunderstood that chapter.

7. I wish you had spent more time talking about invariants. I'm slowly coming to believe they may be the most critical thing to think about when creating a design.

So I'd be interested in more of your perspective on that.

Ok, those are the primary things that stood out to me. I'd be interested in your thoughts on those, especially 3, 4, 6, and 7.

I'd like to ask if you'd be interested in reading the current draft of my book.

I would be interested in any high-level feedback or commentary you might have. I'm not too worried about the specific wording at this point unless the meaning is unclear.

To be clear, I understand that this is not a trivial ask and you are no doubt quite busy. I am a completely random person and in some sense this is an entirely unreasonable request.

You certainly have no obligation to me; the default expectation here is "sorry, no." Such an answer will not hurt my feelings.

Thanks for writing "APoSD". I enjoyed it, and I'll be recommending it to others.

- John Mark Wilkinson

[John Ousterhout]

Hi John,

I've made a few comments inline in your message below.

On Sun, Mar 2, 2025 at 9:14 PM John Wilkinson <john.wi...@rocky.edu> wrote:

3. In "Different Layer, Different Abstraction", you talk about "Pass Through Variables", and end by saying "Unfortunately, I haven't found a better solution than contexts." (page 59)

I believe the problem completely disappears simply by not mixing construction graph logic with business logic.

I haven't heard the term "construction graph logic" before; what do you mean by that, and not mixing it with business logic? 

4. In Chapter 6, in the section "Push specialization upwards (and downwards!)", there is no distinction between which kinds of specializations to push up vs. down.

I realized while reading that section that I haven't thought about it in those terms, but I do this.
Specifically, I push specialization related to concrete behaviors (implementation details, perhaps) down, and I push specialization related to usage up.

So higher-level things decide how they want to use the thing, and lower level things decide how they want to interpret that usage. Or something like that.

Seems reasonable.

6. In Chapter 15, "Write The Comments First," you talk about using comments as a design tool.

I don't think I agree with this. I mean, sometimes I sort of do this: I'll start by vaguely mapping out my idea via a sequence of comments, and then gradually fill in the details.

But most of the time, I'll rapidly prototype something, and then throw it away due to some behavior or ergonomics that I don't like, and then repeat.

Thinking about the process in terms of your book, I'm searching for the right interface.

Often, I'll add mock out code and use cases that aren't needed yet, and may never be needed, to sort of push on the design, to test its limits.

And then when I discover the right design, where all those pieces sort of just fall into place, I remove all the mocked out garbage, 

do a refactor pass to clean everything up, and during that pass I'll put in the comment with details about the design and how to use it and extend it.

Basically communicate why the design is the way it is.

But I can't do that up front, and I don't think I can do that with comments.
It's easy to comment that something should work some way, it's hard for me to figure out if that really for real makes sense when it comes down to it.

I need code to know that for sure.

But maybe I misunderstood that chapter.

Sounds like we might disagree on this, but if your approach results in code that is clean and easy to understand, then I have no objection to that. 

7. I wish you had spent more time talking about invariants. I'm slowly coming to believe they may be the most critical thing to think about when creating a design.

So I'd be interested in more of your perspective on that.

I definitely find invariants useful, but I don't see them as "the most critical thing to think about when creating a design". For example, making things (somewhat) general is higher on my list.

 

I'd like to ask if you'd be interested in reading the current draft of my book.

Your book sounds interesting, but unfortunately I have so many things on my plate right now that I'm not likely to get to this anytime soon. Sorry about that.

-John- 

[Paul Becker]

John W,

I read your email with interest last week, but haven't had a chance to properly ponder and add my thoughts.

I just wanted to add that there are others on this email list who might be interested in reading the current draft of your book, if you're interested in expanding the offer.

paul

--
You received this message because you are subscribed to the Google Groups "software-design-book" group.
To unsubscribe from this group and stop receiving emails from it, send an email to software-design-...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/software-design-book/CAGXJAmwyWbNwwbGEm%3DiuYdy7-UHLaBjY5aDV0ri-Fhf5p21ZjA%40mail.gmail.com.