A simple blog made with Zola and Duckquill Zola 2026-03-25T00:00:00+00:00 https://cetanu.github.io/tags/design/atom.xml 2026-03-25T00:00:00+00:00 2026-03-25T00:00:00+00:00 Vasilios Syrakis https://cetanu.github.io/blog/a-philosophy-of-software-design/ <p>Today I finished reading the book, “A Philosophy of Software Design”, by John Outsterhout, a professor at Stanford University.</p> <p>I wanted to write a little about what I learnt from the book, plus how I see it mapping to my experience in my work where I’ve dealt with software and choices around design.</p> <h3 id="complexity-is-incremental"><a class="zola-anchor" href="#complexity-is-incremental" aria-label="Anchor link for: complexity-is-incremental"><i class="icon"></i></a> Complexity is incremental</h3> <p>This is probably obvious to anyone who has worked on software in any serious capacity, but (unless you’re vibe-coding) complexity doesn’t just show up in a single pull-request.</p> <p>It’s the “Boiling Frog” problem, except you’re not the frog, you’re the chef…<br /> If we increase the temperature by just one degree, surely it’s not that bad, right?<br /> This is how we justify adding complexity to ourselves when we say “it works for now, I’ll clean it up later” on a pull-request.</p> <p>The incremental quality of complexity is what makes it so insidious, because it’s so easy to trade a small bit of complexity to get something delivered. You can even continue to make that trade-off, again and again, for years. Who cares if an abstraction leaks a little bit, as long as I can fix up this edge case right now?</p> <p>It’s hard to pinpoint the exact moment when things become sluggish, hard to change, prone to errors, and difficult for new engineers to understand. That’s because there’s no exact moment.<br /> Just like how a frog doesn’t suddenly start boiling when the water goes from 99°C to 100°C.</p> <h4 id="it-s-shared-discipline-not-a-technical-challenge"><a class="zola-anchor" href="#it-s-shared-discipline-not-a-technical-challenge" aria-label="Anchor link for: it-s-shared-discipline-not-a-technical-challenge"><i class="icon"></i></a> It’s shared discipline, not a technical challenge</h4> <p>I might be totally wrong on this, but I get a general sense that when people think about complexity, the focus is on technical decisions that get made over time. It almost implies that you can solve complexity all by yourself if you just work hard enough.</p> <p>We work with other people. I believe it’s more pragmatic to shift this perception so that the focus is on person-to-person interactions - which I assert is where the problem arises.</p> <p>When a reviewer fails to stand their ground, complexity is welcomed in. This can be tricky, because often you’re standing against a peer who you trust, who means well, but who might be too busy to spend the extra time to come up with a design that doesn’t attach one more tiny anchor to the codebase.</p> <p>I comfort myself by thinking that nobody intentionally adds complexity. They can’t see a better way, or maybe they didn’t ask themselves if there could be a better design. Thinking takes energy and I don’t blame anyone for taking the path of least resistance to get their work done. Perhaps what we need is better ways to measure complexity, so that we can reward its reduction.</p> <p>For people working solo, you are both the author and reviewer. If you aren’t trying to see your own work from a different perspective, then your “reviewer” persona is effectively rubber-stamping the work, shrugging, and walking away.</p> <h3 id="abstractions-are-about-hiding-unnecessary-details"><a class="zola-anchor" href="#abstractions-are-about-hiding-unnecessary-details" aria-label="Anchor link for: abstractions-are-about-hiding-unnecessary-details"><i class="icon"></i></a> Abstractions are about hiding unnecessary details</h3> <p>This one probably sounds like common sense. Duh! That’s what an abstraction is.</p> <p>However, for me, I think it’s valuable to consider that you and I sometimes make abstractions that accidentally hide <em>necessary</em> details.</p> <p>This is one of those things where, if you zoom out a little bit, makes software engineering seem like such a challenging field. The subjectivity of this - where to draw the boundaries of an abstraction - highlights a constant cognitive requirement towards making a balanced decision.</p> <p>You can’t open a book and have it tell you how to make the right abstraction. You just have to fail, walk into a mess, learn from the mess, and make the next project better, only to fall into another mess. A mess that grows as it feeds on entropy and junior developers.</p> <h3 id="deep-modules-are-simpler-than-shallow-modules"><a class="zola-anchor" href="#deep-modules-are-simpler-than-shallow-modules" aria-label="Anchor link for: deep-modules-are-simpler-than-shallow-modules"><i class="icon"></i></a> Deep modules are simpler than shallow modules</h3> <p>First, what does this even mean? What is a deep module?<br /> A module is deep when its implementation is large compared to its interface.</p> <p>That means that you could have a module that is long (in terms of lines of code), but if every function in that module is exported, the interface is large.</p> <p>Instead, a deep module would be something with perhaps a few key functions or classes exported, which encapsulate the implementation behind a concise interface.</p> <p>This was something that surprised me at first but makes total sense. If make a library, I don’t want the caller to have to know about 20 different functions or methods that they need to call, especially if most of the time all of the arguments passed in are very similar.</p> <h3 id="general-purpose-code-is-simpler-than-special-cased-code"><a class="zola-anchor" href="#general-purpose-code-is-simpler-than-special-cased-code" aria-label="Anchor link for: general-purpose-code-is-simpler-than-special-cased-code"><i class="icon"></i></a> General-purpose code is simpler than special-cased code</h3> <p>What exactly is the difference between the two?<br /> General purpose code solve a class of problems. Special case code solves one problem.</p> <p>Example:</p> <ul> <li>Special case: A function that adds the <code>Authorization</code> request header with a particular value</li> <li>General purpose: A function that adds a request header, with a given key and value.</li> </ul> <p>Special cases pop up in codebases after their initial design has been implemented, a bunch of users have been onboarded, it’s operating fine, but one particular (and important) user needs it to do something that wasn’t in the original design. This is expected in software, and rigidity isn’t a good response.</p> <p>If you immediately know how to change the system so that their particular need is solved as a general case it’s a clear win, but this doesn’t seem to be how things go in most cases. Instead, it takes painful thinking to determine what needs to be rearranged, migrated, and mutated, in order for the special case to be handled in such a way that it doesn’t require someone to carve out time from their day to maintain it.</p> <h2 id="philosophy-not-science"><a class="zola-anchor" href="#philosophy-not-science" aria-label="Anchor link for: philosophy-not-science"><i class="icon"></i></a> Philosophy, not Science</h2> <p>There is a particular theme that seems to be common across the above concepts.</p> <ul> <li>What makes a good abstraction?</li> <li>How deep should a module be?</li> <li>How general should my code be?</li> </ul> <p>There’s no formula. A book can’t teach it to you. A committee can’t develop a standard for it.</p> <p>The fundamental question being wrestled with is “Where do I draw the boundary?” and the answer is different from wherever you are standing.</p> <p>It’s the human factors that help answer this question. How much cognitive load can the user or reader bear? How often will I have to change the codebase? A compiler or linter can’t answer these questions. It requires a person to draw a subjective line in the sand and then defend it.</p> <h3 id="the-element-of-taste"><a class="zola-anchor" href="#the-element-of-taste" aria-label="Anchor link for: the-element-of-taste"><i class="icon"></i></a> The element of “Taste”</h3> <p>I hear about how the future of software will be influenced by having good “taste” now that LLMs are writing all the code (I don’t actually believe this).<br /> If that’s true then I sincerely hope that all the people that intend to map their taste into software learn good software design first.</p> <p>Ironically, the way to learn good software design is through experience. You have to ship something and collect the feedback. Sometimes that feedback is customers telling you what causes friction. Other times it shows up in the volume of questions directed at a particular feature… at 3AM after your site blows up.</p> <p>While reading the book you get a sense that it’s never going to answer this question, “What’s a good abstraction?” because it can’t. The professor encourages people to find the right balance for themselves, and it introduces distinctions that might enable them to do so.</p> <p>You might be creating a good design if the abstraction aligns with a business domain, or when you provide a neat general-purpose interface across an entire system. You might be creating a bad design when you add logic that purely addresses an immediate need and nothing else.</p> <h2 id="my-closing-thought"><a class="zola-anchor" href="#my-closing-thought" aria-label="Anchor link for: my-closing-thought"><i class="icon"></i></a> My closing thought</h2> <p>Writing this page made me realise that these problems that I found unapproachable - how to decide where to draw the line - are simply the way things are. It’s the essence of design.</p> <p>Just like other art forms, you can practice, fail, learn, and improve, but there will always be some people that either love or hate the art that you created.</p> <p>Often that person is your own self. The inner-critic looks at the past and is ashamed of mistakes. I choose to forgive myself for the imperfections and focus on the parts that I’m proud of.</p>