Book Review – Kaj Ström

Clean Code by Robert “Uncle Bob” Martin et al. is all about writing maintainable code. The core tools presented for this goal are refactoring, test automation and paying attention to the clarity of the code. The book has a lot of code examples in Java, which is seems to be the lingua franca of software development books.

The book is organized into chapters that address clean code at different levels like naming in general, functions, classes, modules and even at system level. There is a chapter and an appendix dedicated to dealing with concurrency. One brief chapter is also dedicated to emergent design. In the end of the book there are case studies of cleaning up open source classes.

The first chapter “Clean Code” lays some foundation on what clean code is why it is necessary to focus on keeping the code clean. The chapter also contains quotes from well-known programmers on what they consider to be clean code. Their answers are a pretty interesting read and a good addition to the chapter.

I think anyone with a few years of professional programming experience knows what it is like to deal with bad code, the dreaded legacy codebases with incomprehensible code and dependencies all around. Change one thing and something completely unrelated breaks and you have no way of finding out except trying to manually test everything, which you obviously cannot do on a project of any meaningful size. So it is left for the users to find the bugs and each release becomes a stressful event of waiting to see what broke and how many users get upset.

But to state the (likely) obvious, bad code will kill your productivity over time. In the beginning it is fast to just get things working as quickly as possible, then the technical debt starts to accumulate and everything gets slow and horrible. Some technical debt always accumulates even if you try to stop it, but not caring about it will likely result in a disaster over time. There is a time place for calculated risks and taking on technical debt, but that shouldn’t be the default mode of development.

To keep the code clean the book offers two key methods Opportunistic Refactoring(The Boy Scout Rule) and cleaning up new code right after it was written (First make it work, then make it right). Getting a good solution to a problem on the first try is very hard so I think it is worth it to go over the code in order to see how to make it cleaner. Needless to say comprehensive tests are required to ensure nothing gets broken while cleaning up.

The different chapters are full of great tips to make your code more clean and maintainable at different levels. Some things that I have focused on more after reading this book:

Keeping methods even shorter.
Write methods that do only one thing.
Ordering methods inside a class so that a method is defined after it is used the first time. This ends up in a structure where high-level functionality is specified before the low-level functionality and it is easier to browse the code.
Being critical about comments. I used to use a lot of PHPDoc comments, but with PHP 7.1 type hinting these are mostly just noise.

The first two are nothing new to me, but getting repeated reminders of these seem to always change the way I write code.

One of the things in the book I didn’t like was chapter 16. This was a quite long chapter on refactoring SerialDate. To me it felt like it suffered from it’s implementation pretty badly. Reading the chapter involved constant shuffle between chapter 16, code smells chapter and the appendix that contained the actual code of SerialDate. Perhaps this would have been better conveyed through some other medium than a book.

In general I think this book would be of the most value for programmers just getting started with professional software development. More experienced programmers will likely learn some new tricks as well. The book is quite easy to read in comparison to Code Complete 2 which covers many of the same topics. I still haven’t managed to finish Code Complete even though I think it has some excellent information.

I would have liked to see something on the domain of the software being written. I think it is an extremely important aspect of producing useful software. It doesn’t really matter how clean your code is if it does the wrong things. But it’s a large topic in itself and understandably a single book can’t give you everything.

Some similar and related books I’d recommend

TL;DR; Highly recommended read if you are a junior developer. More experienced developers should remind themselves of these things periodically, there always something you missed. Maintainable code matters. Some parts are difficult to read due to having to having to back and forth different chapters in the book.

I recently finished reading Vaughn Vernon’s book Reactive Messaging Patterns with the Actor Model. The book is about how to use the Actor model with Scala and the Akka toolkit.

First three chapters of the book concentrate on giving the reader a quick introduction to Scala, Actor Model and Akka. Personally I enjoyed these three chapters the most in this book. They we’re quick to read and provided so much information for me as I had no previous experience with neither Akka or the Actor Model.

Bulk of the book is the chapters following the first three that are messaging patterns inspired by Enterprise Integration Patterns. Thus the last seven chapters are basically a pattern catalog. This is something I have heard critique from few other people, especially people who have read Enterprise Integration Patterns (I haven’t, yet). I admit pattern catalogs are heavy to read and I too struggled with reading the quite intensive examples. But, these also provided me with the most practical knowledge of Akka and the Actor Model. I made use of some of the things I learned in the catalog almost right away when I did some exercise programs with the Akka toolkit. There is some really good stuff in there.

One thing I found especially interesting was the Transactional Actor pattern in Chapter 9. This pattern explains how to persist actor state with Event Sourcing and thus gives some insight on how to use actors to implement Aggregates. This is something I am planning to try out in the future. Event Sourcing is a really natural fit for persisting actors so I’m looking forward to playing with this.

It’s a shame that Akka Streams were still in the planning phase when the book was written, this is something I would like to learn more of at some point. The book covers PersistentView very shortly, these can be used to denormalize persisted actor state for use in view logic. This is something I would have liked to have seen a more thorough example of in the book. It is still a bit unclear to me how to denormalize actor the state for view logic in practice, but apparently Akka Streams is the correct way to it now(?)

Even though I do not use Scala at work, I learned new things to consider in other environments as well. Most prominent at this time is the differentiation between types of messages. Consciously separating Command Messages, Event Messages and Document Messages is something I have concentrated on when using JavaScript event/messaging libraries. It’s interesting how learning unrelated technologies always seems to teach something that’s useful event if you cannot use the technology itself.

TL;DR; I liked the book. Some chapters heavy to read, but provide valuable information. Read if you are interested in Scala and Akka.