My learnings from the book "A Philosophy of Software Design"

Table Of Content

• Solid recommendations I agree with
• Implementation comments: what and why, not how
• A philosophy of software design - John Ousterhout
• Chapter 5 — Information Hiding (and Leakage)
• Define Errors Out of Existence
• How can social robot use cases in healthcare be pushed - with an interoperable programming interface
• Chapter 14 — Choosing Names

Pass-through variables add complexity because they force intermediate methods tobe aware of their existence, even though the methods have no use for thevariables. Below are the notes I made on takeaways from the book and my thoughts on acouple of the ideas (minus some fun references to real code that I've workedon). I'm publishing the notes as it's a nice way for me to re-read them andretain the information. This doesn't cover all the content in the book, and it'spossible that I misrepresent the author in some of my paraphrasing. If you'reinterested in the content I definitely recommend buying a copy - it's notexpensive and it's an easy read. What makes it especially great from a software related book, is that there is really not a lot of code to read and for what there is, it is just to relay an idea.

Solid recommendations I agree with

However, it turns out that the most common use of unset was to clean up temporary state created by a previous operation. But it was hard to know how far the previous operation had progressed, so it was hard to know if a variable had been created or not. Thus you had to be prepared to handle exceptions from unset in a lot of places. It would have been much more useful, and simpler, if unset had been defined to mean that it ensures a variable with that name does not exist after it has been run, regardless of if it existed before or not. If your code throws an exception, you are forcing all callers of that code to be prepared to handle it if it happens.

Implementation comments: what and why, not how

Writing up, sharing, and debating design with other peers is a practice more and more common in tech companies. This includes both whiteboarding and presenting to a group of peers, as well as more formal RFC-like design processes. While it might be less applicable to the course John taught, it's a practice that comes with many benefits. These days, as shared editing and commenting tools are more common, with editors like Google Docs and O365.

A philosophy of software design - John Ousterhout

This kind of decomposition has a different purpose to designingpublic interfaces, but sometimes get added to the public API of a class ormodule. The primary focus of the book is about attempting to eliminate or at least reduce complexity in software. This can be achieved by taking more time and consideration in the design and thinking about the implications of design. Related to the concept of deep modules is the advice to make them “somewhat general purpose”.

Technical debt and architecture debt also don't get much mention or discussion, which is in contrast to my day to day work. It would be nice to see a later version touch on these topics, as well. The book is an easy read, thanks to its short sections and good bolding. Most importantly, the book stays humble, does not try to convince, but offers perspectives backed by easy to follow examples.

It was one of the primary sources of making procedural/spaghetti code and the source of many unpredictable bugs. I agree with the author that we should write comments if we have to explain something tricky (such as an algorithm or something similar) or non-obvious (why, not how). In addition, the author mentions a famous API design antipattern involving overexposing internals, which later adds to an architecture debt. One way to make code more obvious to the reader is to have blank lines betweenparts that are logically separate, and maybe to preface the code block with animplementation comment. The overall complexity of a system can be determined by the complexity of eachpart, weighted by the fraction of time developers spend working on that part. Ifyou isolate complexity in a place where it will never be seen, then that'salmost as good as eliminating it entirely.

The philosophy and practice of our hybrid workplace - The Official Microsoft Blog - Microsoft

The philosophy and practice of our hybrid workplace - The Official Microsoft Blog.

Posted: Mon, 22 Mar 2021 07:00:00 GMT [source]

Pass-through methods are shallow and add complexity

There isn't much to say about this, other than thatI intuitively agree. The book is also quite small and light which makes a great read for your daily commutes. The author emphasises the benefits of trying to stay in Technical Credit rather than Technical Debt. John, on the other hand, had the vantage point of having multiple teams solve the same design problem during a semester, with him observing. With each repeat, he was able to both validate and tweak his observations.

Still, they all present interesting viewpoints, backed with examples. They also make for potentially sound advice to give, when mentoring less experienced engineers. Ousterhout argues that the best modules are those that provide powerfulfunctionality, but have a simple interface. He describes these as deep modules,in contrast to shallow modules, which have a complex interface but not muchfunctionality, thereby not hiding significant complexity. After that, you have to concentrate on speeding up the most commonly executed path. Currently maybe several method calls are used, but perhaps all the work could be done in a single method call.

It continues with the standard advice of always measuring instead of assuming. When optimizing, the biggest gains can usually be had by fundamental changes. For example by introducing a cache, or changing the algorithm or data structure. As a budding developer, using jQuery extensively taught me the importance of simple interfaces in driving adoption of your code. On page 68, the author mentions the GOTO command to eliminate duplication by refactoring the code so that we can escape from the nested code. This is a big surprise, as the GOTO command has been considered a terrible idea by most authors for decades now.

It's awell-structured, concise read about managing complexity in software design. An example of a deep module is the Unix/Linux system calls for I/O operations. There are five of them (open, read, write, lseek, close), and the signatures are simple, but they hide an enormous amount of implementation details on how files are stored and accessed on disk. In contrast, an example of a shallow module is the Java I/O classes. In order to open and read from a file, you need to use a FileInputStream, a BufferedInputStream and a ObjectInputStream.

Sharing design ideas upfront and opening a debate using these tools is a great way to build more sturdy architecture. Especially when applying the "design it twice" principle, and writing up alternative designs considered, and the tradeoffs why the other design was not chosen. Still, I wondered just how much I would learn about software design from experience partially distilled from a classroom - even if a Stanford classroom.

You often throw an exception because you don’t know what to do in that case. But if you have trouble knowing what to do, chances are the caller also has trouble knowing what to do. If you can define your functionality such that it never needs to throw an exception, then you have reduced the complexity of the system. There are few books that discuss software design in a simple and approachable way, while leaving the reader novel and practical concepts to use. A Philosophy of Software Design is a standout and recommended read for this reason.

However, in my opinion, the documentation of a system is not the sum of the comments. It is a separate document that describes how the system fits together. Extracting the JavaDoc comments from all the classes does not become the documentation. Nothing highlights which classes are most important, and what the overall structure is. The chapter on optimization starts by listing typical times taken by various operations such as network communication, I/O to storage (disk, flash), memory allocation and cache misses.