Clean code and the art of readable code a summary
Readable code is a subject of discussion among developers aiming to improve their code skills and also thinking about the human side of the code, indeed, the machine executes the code and doesn’t care about the readability or maintainability of the code, instead, this chore, is part of the daily life of programmers. Readability can be interpreted in different ways by different people, therefore, there are initiatives to at least create a common sense. (Boswell & Foucher, 2011).
Previously I reviewed the book “The Art of Readable Code” (Marabesi, 2020), this time, the focus is to compare the differences and similarities between “The art of readable code” and “Clean Code”. Despite both books being opinionated, they provide a common ground for developers to build on top of and begin a discussion around that.
Naming things
The first subject addressed here is the naming convention that is stated by both books to be important, with the argument being that we are coding for humans and not for machines. The study path created by (joebew42, 2021) gives a point of attention for naming as well, as it is one of the sections listed to be read on the Clean code book.
Not only that, David Thomas and Andrew Hunt dedicated a section to talk about naming things in code, they also agree that naming is hard and renaming is even harder. What caught my attention is the story behind the i, j and k convention for loops, the convention came from 60 years ago as it was part of the FORTRAN language. Even though this became as standard across the industry (you see today still loops with those variables) they are not that helpful when reading code.
Furthermore (Hermans, 2021) also points to a not-so-productive way of improving code understanding with obvious comments:
Low level comments, on the other hand, such as “Increment i (by one)” after a line that reads i++; , can create a burden on the chunking process.
The Programmer’s Brain by Felienne Hermans, pg 28
Besides that, she also agrees that naming things is hard. For that, she elaborates on previous research to understand why is that the case. For further elaboration on this, I would recommend some bits of the programmer’s brain review.
Comments
This is where the two books diverge most, and the divergence is a difference of principle rather than of taste. Clean Code treats a comment as a failure to express the intent in the code, and the chapter is largely about limiting the damage when a comment turns out to be unavoidable. The Art of Readable Code treats a comment as the place to record what the code cannot carry, which is why its chapter is organised around what a reader needs to know that the identifiers do not say.
The practical difference shows up the moment a comment is needed. Clean Code sends you back to the code to try to remove the need for it. The Art of Readable Code asks what the next reader will not be able to infer, and writes exactly that down. Both produce fewer, better comments, and they get there by different routes.
Where the books agree and where they diverge
| Subject | Clean Code | The Art of Readable Code |
|---|---|---|
| Who the code is for | The person reading it, not the machine | The person reading it, not the machine |
| Naming | Names should reveal intent | Pack as much information as possible into each name |
| Comments | A failure of expression, to be minimised | The place for what the code cannot express |
| Functions | Small, and doing one thing | Not the organising idea, readability is |
| Form | Prescriptive rules, with the reasoning given afterwards | Heuristics and measurements, rarely absolute |
The last row is the one that matters when you choose which book to hand to someone. Clean Code is easier to follow because it gives rules, and easier to misapply for the same reason. The Art of Readable Code asks the reader to internalise a criterion, the time it takes someone else to understand the code, and then apply it to situations the book never covers.
Same goal, different instruments
Neither book is a substitute for the other. Clean Code gives a set of habits and a shared vocabulary a team can agree on. The Art of Readable Code gives a way to judge code the rules do not cover. Read together, the rule book is what a team starts from and the criterion is what keeps the rules from hardening into dogma.
You also might like
About this post
This post was written entirely by a human, without AI assistance.