Behold! Yet another developer joined the club of “clean coders”! …Or at least gotten through the well-known book Clean Code by Robert C. Martin aka. Uncle Bob. Before I started reading it, I had a lot of fellow developers and colleagues recommending me to give it a try. According to them, the book was the best knowledge source for improving a developer’s capabilities to refactoring code. I therefore thought would give my opinion and reflections on whether or not it was worth it. Should every developer read it?
For starters, for those who do not know what the book is about. Clean Code is, as it says reading, “a handbook of agile software craftsmanship”. So, what does that mean? To put it in my own terms it is a developer book about how we, as developers, have the responsibility of managing the quality of the code. Quality of code refers to how manageable the code will be in the future. Low quality equals high maintenance cost and increased risk of bug creation when implementing new features. Also referred to as Code Smell. On the other hand, the high quality of code obviously means the opposite.
To give the idea of how the book tackles the objective of increasing the quality of code I have listed a few of my favorite learning points from the books:
Although this lesson comes quite fast as a new developer, I can only emphasize how important I believe this point is. Writing the action which a method performs and the noun that an object represents can make even the most unstructured code seem logical.
If you ever have a discussion of whether a method or variable needs a more elaborate name, I advise you to give it a long and detailed name rather then a short and undescriptiv name. Readability is of cause important, but not more important than making your intent clear.
Any method should only do one thing, and it should do that thing well. This is called the Single Responsibility Principle. Do not make a method called handleRecipe(), which starts by retrieving all the necessary information, adding it all together, accounting for the taxation, accounting for the tip and allocating it to the intended waiter, print out everything and finally add it to the total revenue of the restaurant.
This method does not only do several different things, but it also changes the level of abstraction. Instead split it up into different levels of abstraction. Dependent on the developer, the level of abstraction might change. However, I would argue that something like adding a single bill to the revenue of the restaurant should be placed somewhere else on a higher abstraction layer. Likewise, it could also be argued that things like allocating the tip to the intended waiter should be within its own method.
Ever had a method that you needed to do something else if a condition changed? Sure, you have! I have tried this scenario way too many times. However, what is the correct way of solving this issue? Just add an extra Boolean argument indicating whether the condition is true or false. Wrong!
A method which changes behavior dependent on the state of a Boolean is a clear indication that the method does more than one thing. Therefore, there should be two methods and each method should have descriptive names, which makes it clear what the difference is.
The optimal number of method arguments is to aim at zero. The method should have a name which makes it obvious what it intended to do. Additionally, it should also be within a class which only worked with the fields that had a clear logical link to the class. Thereby it would not be necessary to for example pass a model-object around as a method arguments, if it is obvious to all that the updateModel(), actually does what it says.
Of course, scenarios occur where methods will have arguments. However, keeping the number of arguments low is still incredibly important. One argument is okay because the developer is capable of providing a meaningful name to the method which explains what this argument is used for. E.g. setName(name) or getShapesDiameter(triangle).
This sets the golden rule, if it is not possible to determine what the arguments of a method call are used for, then there is something wrong. Either the naming is off or there are too many arguments with no obvious link to the method’s intention. Increasing the number of arguments can therefore only be defended if there is a clear link.
Comments are an excuse for a badly written code. The developer has thereby thrown in the towel in terms of naming methods correctly and adhering to the Single Responsibility Principle
Whoever wrote the comment did it with good intention. In the hopes that it would give the next reader the necessary information to understand the code’s intent. However, unlike method names, comments are not updated over time as the code develops. Moving a module around into another context is at the same time given a new name matching its new purpose. Renaming methods, classes, and variables are quite easy with all the IDE’s (Integrated Development Environment – e.g. IDEA) refactoring tools. However, even though some IDEs include comment renaming, I personally do not feel that the function has the same consistent effect on comments as it has on the code. Maybe that is because the comment is not written with the same consistency as the code. The code will not compile if the naming is not consistent, while comments will pass right through.
This also highlights another point. If a comment is necessary, so is the writing of that comment. Comments are written with the same amount of effort as the code.
A method retrieving and manipulating variables from another class is showing that it is envious of the other class’s scope. If a method is envious, it most likely means that it is in the wrong class. Manipulation of variables should only be happening in the class which holds the variables. Otherwise, it quickly becomes a mess of where the modified variable resides.
As you can see I had several learning points from the book, and even though I only showed a few here, there are more equally valuable.
Given that the book is not intended for a specific level of developers, it includes guidelines on both a beginner and advanced level. This also means that some of the guidelines will be obvious why they are important. Sometimes I would argue that it even dived too much into these obvious guidelines. To take an example the DRY (Do not Repeat Yourself) principle is essentially a matter of duplication. Why would I need multiple sections in the book explaining why this is bad? Anybody who has a bit of experience writing code will know this.
Likewise, I do not need a guideline to tell me to delete dead code. Unused code is useless code. For me to explain the many reasons why, would contradict my own reasoning why it is not necessary to write about, so hopefully you are able to figure that one out yourself.
Let me make this clear, I believe that any aspiring developer could be recommended reading this book. Which is also what I believe is happening in the developer environment today. It is a well-written and large collection of coding guidelines.
Side note – I found another article where the author quickly goes through all the guidelines taken from chapter 17 of Clean Code Link. Skimming through this article might quickly indicate whether or not this developer book would be good for you to read.
… and back to my evaluation. No doubt the book is of high quality and contains valuable content. However, it pails in comparison to a quality-oriented developer environment. Working with the right people, pair programming and reviewing code is all much more helpful in the development of a high quality of code. I believe that Uncle Bob would agree with me on this point. Clean coding is not only about knowing the guidelines. It is much more about training yourself how to implement those guidelines.
Although I by now know all of the guidelines, I will be honest and say that I do not always write perfect code. However, being aware of this makes me capable of continuously developing my skill. In my opinion, the best place to improve the quality of your code is when two developers sit down in front of one screen and start a meaningful discussion. Therefore, if you decide to pick up Clean Code, remember that it is just a book. You have the responsibility of putting it to work.
I hope that you enjoyed my review of Martin Robert’s book. Currently, I am in the process of getting through my developer book bucket list. Therefore, I hope to make another review sometime in the near future. I decided to tackle the second most famous developer book on the market: Head First – Design Patterns.
My name is Daniel H. Jacobsen and I’m a dedicated and highly motivated software developer with a masters engineering degree within the field of ICT.
I have through many years of constantly learning and adapting to new challenges, gained a well-rounded understanding of what it takes to stay up to date with new technologies, tools and utilities.
The purpose of this blog is to share both my learnings and knowledge with other likeminded developers as well as illustrating how these topics can be taught in a different and alternative manner.
If you like the idea of that, I would encourage you to sign up for the newsletter.