Review: A Philosophy of Software Design

You have been in technology for a minute or two, and now have become a picky reader. Your reading list is full, but your next pick is a careful one. You hope it holds up to your expectations, and... surprises you. How often does that happen now? Twice, three times in a good year? A book that stands out among your recent picks. For me, A Philosophy of Software Design is that book.

In fact, some of you, dear readers, have written permission to stop right here. Do yourself a favor, get the book and start reading. But for you, the more inquisitive, or... more skeptical, let’s find out why.

Before we begin, I must say something. I don’t recall why I added this book to my wishlist. I only know that it was early this year — Amazon says January 9th, 2020. Was it a mention on the socials? A casual post or comment? I don’t remember. But, I want to thank whoever recommended or mentioned this book online early this year.

Now, this book is great, first of all, not because of the subject itself: writing better software. But because of reasons I have written about time and again. And I will keep at it until enough people get it. It is a short read; 170-odd pages. It is well written; no rambling. It is well structured; each chapter covers one topic and covers it well. Your interest in writing good software is the only required background.

Also, this book offers practical advice when it can. And when it can’t, it tells you why. Wow!

Alright, I like the style of Brian Kernighan. And you do too. You know, books like the two Software Tools. Or The C Programming Language. Or The Practice of Programming. Etc. I got the same vibes with this book. And it wasn’t a coincidence. The author, John Ousterhout, best known for Tcl and Tk, talked to Brian Kernighan. And I knew I was reading someone who likes and writes in a style we both appreciate.

At the beginning of the book, the author calls out complexity. The main antagonist in the quest for ideal software. The protagonist needs to accept that working software is not enough. Complexity is a slow, methodical, and canny foe. And he goes on, in 20 chapters, to explain how to identify and manage complexity. And when that’s done, he summarizes everything at the end of the book. Nice.

It is nice, indeed, to find yourself nodding along as you are reading the chapters. You relate your own experience with the author’s. And connect to philosophical pieces like “pull complexity downward”. Or “modules should be deep”. And link those to your own experience as a software developer.

And then it happens! You reach that chapter that will change your mind forever on a particular topic.

Okay, let’s imagine, an imaginary spectrum representing attitude towards comments in code. At one end, we have the code explains itself gang. At the other, the literate programming crew rolls. I was closer to the code explains itself gang. This book moved me a little bit towards the center.

The book identifies two kinds of comments in code: interface comments and implementation comments. Interface comments already made sense to me. In fact, since Golang started calling us out, I have been trying to be diligent about it in other languages too.

But I misunderstood implementation comments. All these years I thought that clean code and good names were all that’s needed. Yes, they help, but implementation comments help a lot more.

Here’s the gist: to reduce complexity code should be obvious. But sometimes we need to write non-obvious code — straight outta the scientific paper. How to explain these lines of code? The interface comment? The documentation? Those are too far away from the actual lines. No. Implementation comments. They make non-obvious code obvious. Bam!

How many times have I been following someone else’s code, nodding along. Until I reached a line that made me wonder when exactly I got lost. Made me doubt my ability as programmer. Question my existence in the universe...

Or sometimes, it's your own baby that you can't refactor. You've reached the end of your programming language's expressiveness and clarity. Good luck convincing yourself that you should rewrite that fast C code in Python. Again, that’s what implementation comments are for. And that’s the lesson.

That’s my rundown. Now go get yourself a copy.

May 12th, 2020.