Review: “Clean Code: A Handbook of Agile Software Craftsmanship” by Robert C. Martin
There are a few books that I usually suggest to any software engineer who wants to get better at writing clean code. Among them, my favorite is “Clean Code” by Robert C. Martin. This is one of the books that influenced me a lot early in my career and I would like to share a review on it.
Review
I personally like two definitions of “clean code” that are listed in the book. One by Dave Thomas:
Clean code can be read, and enhanced by a developer other than its original author. It has unit and acceptance tests. It has meaningful names. It provides one way rather than many ways for doing one thing. It has minimal dependencies, which are explicitly defined, and provides a clear and minimal API. Code should be literate since depending on the language, not all necessary information can be expressed clearly in code alone.
And another by Michael Feathers:
Clean code always looks like it was written by someone who cares.
Long-term maintenance is the majority of the costs of the software project. The more complex the system, the more time it takes for a developer to understand it and as a result, there are more opportunities to misunderstand the original intent. There are two common sources of bad code:
- A conscious choice in the face of the deadlines — Team makes a call to merge bad code with a promise to spend time on it in future sprints. Many times, it won’t be addressed due to the other backlog priorities especially if the team works in fast-paced environments typical to the startups. As a result, the productivity of the team diminishes with the time until there is a crying need to address the technical debt. The debt will have to be paid at a steep price of a full rewrite of the functionality. The author gives an example where one team took 10 years to rewrite the codebase while incrementally backporting the new functionality. By the time the rewrite was finished, the “new” codebase required another full rewrite.
- Lack of shared design principles and practices enforced through the code reviews — It is easy to write the code that is clear to the author because s/he is deep in understanding of the problem at hand and has full context. The design looks clean and “beautiful” to the creator. However, other maintainers won’t have the same understanding and they might have a different view on what clean and “beautiful” means. To make matters worse, original intent can be lost if the author is no longer with the team. The maintainers introduce new code according to their own standards and understanding. That starts a snowball effect that eventually will completely deteriorate the codebase.
“Clean Code” expresses the opinions of the authors on clean code as a school of thought based on their vast experience in building software. Some of the ideas are controversial, others can be argued with. Uncle Bob, the author, makes it very clear that there are many other points of view on the definition of clean code. The opinion shouldn’t be taken as an absolute but rather as a great opportunity to learn.
The book is organized into three parts:
- The principles, patterns, and practices of writing clean code. It covers a broad set of topics: comments, naming, functions, objects and data structures, etc. A few that I personally like: One level of abstraction per function, Step-down rule to organize code, Learning tests for third-party dependencies.
- Case studies of cleaning up the code. Case studies cover: refactoring of the Command-line argument parser; refactoring of JUnit internals; the refactoring of SerialDate class in the JCommon library. It is very interesting to look at the thought process of the authors and the transformation of the code.
- List of heuristics and “smells” gathered while creating the case studies. It describes the way authors think when they write, read, and clean code. Many of the code smells are borrowed from “Refactoring” by Martin Fowler. Some of the interesting smells: inconsistency in the code; misplaced responsibility; enforce design with structure, not the convention; avoid negative conditionals; choose names at the appropriate level of abstraction.
The authors consider Kent Beck’s four rules of Simple design a good starting point to maintain clean code:
- Runs all the tests — Writing tests forces you to test the design of your code as a consumer. Keeping clean tests is equally important as keeping clean code.
- Contains no duplication — Duplication is a primary enemy of well-designed systems. Extracting commonality at tiny levels can shrink the complexity of the overall system.
- Expresses the intent of the programmer — Code should clearly express the intent of the author. Using good names, keeping functions, and classes small, using standard nomenclature, keeping well-written unit tests are the ways to facilitate with expressing the intent.
- Minimizes the number of classes and methods — a way to fight off the dogmatism and put extra effort in capturing the essence of the design (though the first three rules are more important)
“Clean Code” provides a lot of examples of the code that help to explain the principles and techniques. The book is easy to read and Uncle Bob has his own unique way to engage the audience that is very entertaining.
My experience
There are good books on how to write clean code but like any skill, coding requires practice. You might be lucky to have a great mentor or senior engineer on the team that will help to acquire good coding habits and style through a series of code reviews. But if you don’t have it, a handbook with tips and techniques supplied with good examples will definitely help. “Clean Code” is one of those handbooks.
A lot of things that Uncle Bob covers in the book can be enforced by the right tools that can automatically check code and reject a pull request. However, that greatly depends on the programming language you choose and the maturity of the eco-system. For example, Golang provides a lot of tooling out of the box and forces to write the code in a certain way. Scala, on the other hand, offers a lot of different ways of how one can write the code and that can lead to the undesired state of the codebase. If the tooling is missing then one way to increase the quality of the codebase is by documenting best practices and providing training to the engineers during onboarding while enforcing those practices through the code review cycles. Enforcing two code reviews per pull request is a good way to share the knowledge and produce consistent code.
At the same time, learning different programming paradigms and languages that preach them can accelerate the acquisition of good coding habits. For example, functional programming and the concept of referential transparency provide a different look at how to write the code and that knowledge can be transferred to other programming languages to a certain extent. For example, function composition encourages separating code into smaller functions that do one thing. It helps with code reuse and provides a modular way to combine those functions. Explicit capture of the side effects makes it easier to reason about the program and forces the author to focus harder on the separation of the concerns and split of responsibilities between the code layers.
Verdict
Highly recommended
