#begin

So that’s it everyone! We have discussed the entire book called A philosophy of software design. This was such an awesome book. I believe this book will go into history as one of the great books written about software design, like the GOF design patterns book or domain driven design and clean code. I think all software / game developers and designers should at some point in their careers read these books. Again, you don’t necessarily need to agree with all of it but it’s really great to have this information in your brain so you can act upon it.

Conclusion

We’ve discussed this book enough now but I quickly want to review the information of the book and compare it with some of the idea’s presented in Clean Code to show the contrast.

So I decided to do a blog serie about this book because I wanted to dive into alternatives for Uncle Bob’s Clean Code. The Clean Code book is getting rather dated and there are a lot of mixed opinions about Clean Code, but also about the author Uncle Bob. Some people don’t seem to like him because he’s very prescriptive. Plus he’ll tell you straight to your face if your code is crap and you need to follow his advise in order to change it and reach a clean state of the code. And well, personally, I like that. I rather have someone say it straight to my face instead of giving slight hints on how I should improve my code because they don’t want to make me feel offended. Just tell me, we are all adults. Also remember that people often criticize code, not the person who wrote the code. Sometimes people forget that code is always written with best intentions and with the knowledge at hand and current experience of the developers. And yes, sometimes you look back and think, I, or we should have done it this way instead of that way. These things happen and we simply need to accept that.

But books like Clean Code, and A Philosophy of Software Design are here to help us. There’s so much great stuff in here to set you on the right path and guide you towards clean software design.
As Prof. Ousterhout said in the conclusion of the book, software design is mostly about battling complexity.

So keeping your code clean will have a positive effect on every stakeholder involved in the project, it not just allows you as a developer to stay sane, but it will also allow your manager to sleep at night.

In this book we discovered what Prof. Ousterhout thinks is the fundamental problem of software design which was problem decomposition. How do we take a large daunting problem and subdivide it into small understandable chunks we can digest and reason about. I think this is indeed a very difficult problem in many cases.

We also talked about how working code is not enough. This is also the mantra on Clean Code. We as developers need to write not just code that compiles and works, but which is also understandable, maintainable and of course structurally correct. A way to get there is to understand which mindsets are involved when writing code. According to Prof. Ousterhout there are 2, the tactical mind and the strategic mind. Where in tactical programming a developer soulfully thinks about implementing a feature or fixing a bug as fast as he or she can, not thinking about added complexity, code reuse and anticipating future changes. With the strategic mind however, you do focus your efforts on maintaining complexity and design for reuse and generality and you take possible future changes into account. Prof. Ousterhout also mentions a personality who takes the tactical mindset to the extreme which he calls the tactical tornado. He’s that dude on the team who always meets his deadlines, always manages to deliver something that seems to match requirements but he leaves a mess in his wake which the rest of the team can clean up. The tactical tornado is often praised by management because he or she can come up with solutions really quickly and he or she might get promoted faster but they don’t know that in the end, this person is actively working against them because of the technical debt he brings.

Next up was one of the more famous concepts of this book which was the Prof. Ousterhout’s observation that modules should be deep. I think this is such a nice way of articulating it and also to visualize class or component implementations. Deep modules are modules that provide a really small and concise interface compared to their implementation. Remember Prof. Ousterhout’s favorite interface? The I/O interface of the UNIX operating system. It only provides five functions but it handles everything you need to manage files, interrupt calls, threads, integrating external devices and much more. This is the perfect example of a deep module.

Shallow modules on the other hand are modules that provide a large, often cluttered interface compared to the implementation they provide. John’s example of a shallow module in the book is the linked list class implementation you will find in your favorite programming language. I talked about this before, but I personally think that shallow classes have their place in software design. I mean, should we really delete the linked list class from the programming language, and more everyone implement it himself just because it’s shallow? No! Of course not. These small, shallow utility classes are really nice to have since they raise the level of abstraction, consistency and they can be unit-tested to verify they work and thus you do not need to retest all these custom implementation always and everywhere. So, I think that shallow modules should be considered when they provide useful utilities. But yeah, he’s right when he talks about the stream implementation in Java. Which is built on a decorator design pattern and thus, all these classes are very shallow. Yeah, that’s one of the main reasons I don’t like the decorator abstraction that much anyway. I prefer an abstract factory pattern more, but that’s just me, what about you? Let me know.

A good quality deep modules have is that they hide information and thus don’t leak implementation details. Information hiding is big concept in software design. Not just OO, they fact that OO has access modifiers doesn’t make information hiding unique to OO. Other languages have different means of information hiding through scoping for example. But a nice, concise deep module will hide information. A way to do this is to not expose internal data-structures used inside the module from the module’s interface.

And another really important concept in this book was the advise that your should always try to design a general-purpose solution rather than a special-purpose solution because it will bite you in the ass at some point later in time. Prof. Ousterhout says you should design your modules to be and I quote “somewhat general-purpose”. By which he means you should design your module to tackle the problems or requirements you have today, but also keep in mind you might use that code in a different context as well. This is part of the strategic mind and having an investment mindset.

This all leads to another interesting concept presented in this book which was that, as a designer of the software, you should pull complexity downwards as much you can. This also relates to deep modules again. If you pull complexity downwards, the interface of a module will become simpler. A great tip John gave in this chapter is to consider config files heavily. They can be a really great tool to postpone complexity and put the responsibility somewhere else. But if your system requires a massive config file, or maybe even multiple, you just moved the complexity to someone else. Think about it. For example, if we design out game with a scriptable object architecture in mind. We make it very flexible, but the complexity of getting it all to work is now in the hands of the game designers. This can be a blessing for them, but also their worst nightmare since they are now responsible for managing all the complexities of the inter dependencies of all these scriptable objects. So there needs to be a fine balance. Don’t just shift problems to other stakeholders in the system because it will make your life easier. Remember one of Prof. Ousterhout’s quotes; “When developing a module, look for opportunities to take a little bit of extra suffering upon yourself in order to reduce the suffering of your users.”

Another concept this books gets its popularity from is to define errors out of existence. To my knowledge, Prof. Ousterhout is the first voice in the software industry to articulate this concept in such a nice way. There are probably other people who have insisted on a similar concepts, but the way Prof. Ousterhout presents this concept is just really, really good. Defining errors out of existence means you design your API’s in such a way that exceptions are not part of them. There will always be exceptions but you can design some of you own API’s to mitigate the need for exceptions. Remember the example John gave in the book? It was about the substring functions in multiple programming languages. So for example, in Java, if you pass indexes that are out of bounds, an exception will be thrown, but in a language like Python, I think, when you pass out of range indexes, they will be clamped between the min and max of the length of the string. This is a way to define errors out of existence. And yeah, you cannot always solve problems this way but it’s still a very nice concept to keep in the back of your mind.

We also talked about a very simple, yet effective way to improve software design and that is; Design it twice! Prof Ousterhout taught us to always make at least two designs for something. This allows you to see trade-offs and consider alternatives how ever bad they might seem. Also, when you make yourself design things multiple times you will in the end become a better designer because you gain experience and you will be able to spot bad designs early in the process. This is a really great skill to have since I think that all software developers, are architects as well! You need design skills to properly implement software. If you just follow Jira tickets for example, without considering the design and impact of complexities your code will turn into a mess.

There were also a couple of chapters dedicated to something Prof. Ousterhout is really passionate about as well, and that is; Comments. And I mean, in the beginning I ranted a lot about how I disagreed with John. But he made me reconsider my point of view and I think that comments, in the form of Summaries, in a C# context are really helpful for software design and documentation purposes. Summaries are special kinds of comments that will show up while coding through intellisence. So Rider, VSCode or Visualstudio will show these nice little context menu’s with the documentation of classes, interfaces, functions, properties and variables when you type the code. This is indeed very helpful.

But Prof. Ousterhout also talks a lot about other types of comments which he calls implementation comments, which are simply inlined comments that describe the implementation. These are the kinds of comments Uncle Bob wants you to delete since they are clutter, get out of date and become misleading. I still think that these kinds of comments have no place in the code. I feel that the code must be written and designed in such a way that you just don’t need implementation comments. It’s like Uncle Bob said; Comments are at best, a necessary evil and are just a failure of ourselves to express ourselves in code.

So I still do think that writing as less comments as I can improves the design of the software. And oh, Summaries, I would not consider comments since they are more like meta-data to executable constructs. They serve a purpose.
Another interesting practice Prof. Ousterhout presents in the book is something I would call Comment Driven Development. He tells you to write the comments before you write the implementation of a class since it will allow you to focus on the what and the why, but now on the how since there is no implementation yet. I like this practice since it matches up with Test Driven Development. There are a lot of similarities to these practices like, writing the comment first will make the comments actually useful since they allow you to express your thoughts in natural language before you write them down formally. Also, it’s more fun, since we all hate writing documentation so if you do it after you wrote the implementation you will quickly write a crappy comment because you checked out mentally.

Prof. Ousterhout also has a nice chapter dedicated to choosing names for things in code. This chapter nicely aligns with practices presented in Uncle Bob’s Clean Code. I think both of them will agree with each other on these chapters. Uncle bob says that names should be intention revealing, and I totally agree. Prof. Ousterhout says the same thing in this book so they are on the same line.

And the last topic I want to touch upon is the chapter about consistency. This is a really important concept in software design since consistence really helps with the maintainability and understandability of a codebase. Consistency is not just in naming, but also in coding standards, guidelines and patterns. Try to document these things and enforce the coding standards through IDE settings. So for Rider for example, create a settings repository and make every programmer connect to it to enforce them. Trust me, this will help a lot.

Also, another great thing in this book are the red flags that Prof. Ousterhout will point out every once in a while. These are simple, one or two line tips or tricks to keep an eye out to improve your software design. I really liked this way of pointing out stuff. They were also visualized in these bright red blocks of text so they are impossible to miss. Really cool.

So I hope you liked reading this series and learned something usefull. I certainly did by revisiting all of this information. Especially because I needed to articulate my stance and opinion about everything. It made me rethink some of the concepts like my vicious stance on comments. I really do think now that comments in the form of summaries have a place in software design. So kudos to Prof. Ousterhout on changing my opinion. I guess that’s what he’s aiming at in the first place with all of these chapters dedicated to comments.

Let me know if you have had similar experiences with comments or other subjects in the book. Thanks for reading and let’s see wat the next blogs are going to be about. I have some idea’s but still.

Bye Bye!

#end

01010010 01110101 01100010 01100101 01101110