Posted on by kajstrom

Clean Code

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.