Clean Code — Introduction
This is the first blog post of our Clean Code series which summarizes the famous Clean Code book [1] by Uncle Bob (alias for R. C. Martin). Please share your thoughts below. Enjoy!
Why should we try to write clean code?
It is as simple as this: small things matter. Think of it as the Butterfly Effect. In a palace that has nice architecture, it would take away from its aura if there was a messy table, a door that does not close slightly, a broken window, or junk everywhere. That is why we need to write clean code. Not perfectly or divinely but in an honest way which requires us to do the best that we can. We should never forget that we write code from scratch only once and we need to make it count.
Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. …[Therefore,] making it easy to read makes it easier to write. — Uncle Bob
80% or more of what a Software Engineer does is maintain what is already there. Maintaining should not be waiting for bugs to emerge and fixing these bugs as they come up. Software Engineers should try to prevent these bugs before they emerge during customer use. One can think of it as maintaining a machine. We should fix machine parts that are prone to decay and oil these parts before the need arises or do what is necessary to prevent malfunction. In other words, “Don’t put off until tomorrow what you can do today”. A Software Engineer should refactor forever, as there always is room for improvement. This way technical debt that we need to pay one day will be lower as well as the “Butterfly Effect” that will occur. It is important to keep in mind that, “An ounce of prevention is worth a pound of cure”.
It is a recommended practice to consider in Scrum that refactoring and implementing using Clean Code standards as a criterion in the definition of done.
How to measure code quality?
Bad Code
Managing “bad code” will probably lower a Software Engineer’s motivation to complete tasks and might overwhelm them in the process. It can make companies go out of business just because one day the “bad code” becomes unmanageable as we add more and more features on top of it.
Everyone thinks that they are writing “good code” or they want to write “good code”. If so, why in the world there are many lines of code that can be considered as bad? There are two main reasons. One is, developer leaves cleaning the code for later and unfortunately most of the time this means never. Another one is, developer completely disregards the process of writing clean code and justify themself by saying that the written code works (yay?). Let’s see some of the examples that “bad code” might be written:
- The developer was trying to implement quickly because of the boss’ or customer’s demands.
- The developer simply “did not have the necessary time” for whatever reason.
- The developer got tired of working on the task or was overwhelmed by it.
- The developer has more promised work waiting in the backlog.
- The developer has not been supported by their seniors with the flow of code reviews.
Understanding this badly written code and adding a new feature on top of it or fixing the bugs found in it brings more knots to the already tangled-up code.
Let’s consider the scenario where the bad code is not tried to be fixed and developers are asked or demanded to stick to the project deadlines. To increase the productivity of managing the bad code and developing on top of it, management may hire more and more people but, in the end, the existing mess would get even messier. At this point, the team may notice that they cannot continue to develop, refactor or fix the bugs in the current code base and riot. In the end, management might bend to the will of the developers and greenlight a redesign. However, this might not be the solution as the new code base might become messy as well. To prevent this mess or the previous one, code should be written inside of a set of rules.
Who or what is to blame for the mess? Is it the project schedule, the managers, the team leaders? No, they are not to blame. 100% it is the developer’s fault for not writing clean code. Other stakeholders will always defend their side with passion and developers must defend writing clean code and the time that they spend on writing clean code with the same passion as well.
In 1847, hand washing between patient visits was rejected because of the thought that doctors were too busy and would not have much time. Today this is a must in their profession, any doctor that does not wash their hands would break their “do no harm” vow and in an inspection would be get punished for it.
The Primal Conundrum, according to Uncle Bob is the irony that developers feel the pressure to make messes in the code to meet project deadlines. By doing so they do not take the time to make the production and deployment process faster. By making a mess in the code for whatever reason, they will slow themselves down not only for the task at hand but for the future development as well. This happens because of the entanglement that is formed in the code.
What is a Clean Code or “Good Code”?
According to Bjarne Stroustrup (inventor of C++ and author of The C++ Programming Language), clean code should:
- Be elegant and efficient,
- Have logic that is straightforward to find bugs easily,
- Have a minimum amount of dependencies to easily maintain,
- Have established error handling strategy,
- Be optimal in terms of performance in order not to tempt writing messy code
- Do one thing well.
According to Grady Booch (author of Object Oriented Analysis and Design with Applications), clean code should:
- Be simple and direct,
- Read like prose,
- Have clear intent,
- Not be interpretable or speculative.
According to Dave Thomas (founder of OTI, godfather of Eclipse), clean code should:
- Be easy to read, enhanced by other developers other than the original author,
- Has unit and acceptance tests,
- Has meaningful names,
- One way of doing things instead of many,
- Has minimal dependencies which are explicitly defined, and it provides a clear and minimal API,
- Be literate since depending on the language might not express all information with code alone.
Dave Thomas also makes the broken window metaphor. Other people stop caring about a building that already has broken windows and they allow more windows to be broken. Eventually, they actively break the windows, do graffiti on the walls and let it decay.
According to Michael Feathers (author of Working Effectively with Legacy Code), clean code always looks like it was written by someone who cares. There is not any obvious improvement to the code.
According to Ron Jeffries (author of Extreme Programming Installed and Extreme Programming Adventures in C#), clean code should,
- Run all the tests,
- Contain no duplication,
- Expresses -with meaningful names- the previously set design ideas of the system,
- Has entities that do what they clearly state,
- Be easily changeable.
According to Ward Cunningham (inventor of Wiki, inventor of Fit, coinventor of eXtreme Programming, the motive force behind Design Patterns, small talk and Object Oriented thought leader, the godfather of all those who care about code), clean code should,
- Give what you expect nothing more nothing less,
- Have no surprises,
- Make the language appear simple.
Always remember: Reading code to writing code ratio is 10:1.
Golden Rule = The Boy Scout Rule
One should always leave the “campground” cleaner than they found it. Changes to improve the code does not have to be large. It could be a small change. This change can be renaming, eliminating one duplication, breaking one function into two, or getting rid of one if statement. Every refactor which improves the code and its readability matters.
We have concluded covering up what is clean code and why do we need to achieve it. In the next post, we will talk about naming conventions that we recommend following.
