Book Review: Clean Code

This entry crossposted from Goodreads.

There is a movement brewing in the world of professional software development. This movement is concerned not merely with writing functional, correct code, but also on writing good code. Taking pride in code. This movement is the Software Craftsmanship movement, and one of the people near the head of this movement is Robert C. Martin, also known as Uncle Bob.

His book “Clean Code” is, in many ways, an introduction to the concept of Software Craftsmanship and a guide for developers interested in becoming craftsmen. Clean Code is not about only writing correct code, it’s about writing code that is designed well, code that reads well, and code that expresses the intent of the author.

The book is essentially divided into two parts. The first part contains Bob’s suggestions for writing and maintaining clean code. This includes suggestions on everything ranging from how to properly comment code and how to properly name variables to how to separate your classes and how to construct testable concurrent code. The second part of the book uses the principles in the first part to guide the reader through a few exercises in which existing code is cleaned.

The first part of the book is fantastic. I can’t recommend it highly enough for a professional software developer that wishes to elevate him or herself to a higher standard. This guide is excellent, and gave me lots of things to think about while reading it. I could almost feel myself becoming a better programmer as I internalized Martin’s advice, and the code I’ve been writing has been noticeably better since I began following his suggestions.

In the second part of the book, Martin essentially guides us through three projects: a command line argument parser he wrote, a section of the JUnit source code, and a section of source code from SerialDate. Of these, the most detailed guide is Martin’s illustration of refactoring the command line argument parser.

These sections all suffered from a fundamental flaw: they were inside a book.

These sections all required reading large amounts of source code. Not just scanning it, but really reading and understanding the code, so that the reader can understand the changes Martin makes to the code. Reading and understanding code is something I do every day as a professional, but I never have to do it from paper.

When I read code, I’m interacting with something, not just reading. I can scroll up and down. If I see a method being used and I wonder how it’s written, I can click on it and jump right to the implementation. My IDE shows me symbols in my gutterbar when methods are overridden. I can press a keystroke to pull up a list of just the methods in a source file. I can right click on a method and find its usages immediately. The source code I am reading is something I can push and pull, gaining an understanding of it through interaction.

When source code is printed in a book, you get none of this. To make matters worse, Martin’s code samples have absolutely no syntax highlighting applied to them. When I read source code, certain parts are rendered in specific ways that make it easier to pull the information into my brain. Strings and literals are formatted differently, comments are dimmer so I can focus on code, and so on. Code samples in “Clean Code” are just characters, with occasionally bolding used to draw attention to parts that were changed. It’s amazing how much syntax highlighting helps make code more comprehensible, even at a completely subconscious level.

A book is, quite simply, not an appropriate medium for a guided code walkthrough. I’d have preferred the content of these sections as perhaps a lecture, with Martin’s text done in audio and his code kept on the screen. This would at least prevent me from having to flip back and forth constantly. I didn’t get as much out of these sections as I would have liked to, simply because it was so difficult to digest the information it contained in such an awkward, unnatural medium. At the very least, the code samples should have been printed in color, with syntax highlighting.

I can tell that his advice was good and that the refactorings he applied to the code samples in the book made the code far better, but mostly because I’ve observed these efforts in real life and observed how much they improve code. If I were to encounter Martin’s “before” and “after” code in a project I was working on, I undoubtedly would find the “after” code far, far cleaner and more enjoyable to work with. However, since the book format made it so difficult to understand EITHER code sample, it didn’t seem like Martin’s efforts offered much improvement, even though I know they did.

Despite this frustration, the book is an excellent read, and I’m quite certain it has contributed a great deal to helping me improve as a professional. I can’t recommend it enough, especially for Java developers. I just think that most readers will find the final few chapters intensely frustrating – I recommend downloading the code and viewing it in your favorite code editor so that you can comprehend the source code the way you would any other source code.

Rating: 4 out of 5