If you are a software developer at some point you must have heard about “clean code”. It may come from your technical leaders or your colleagues, but anytime you hear about it, it is always followed by a list of “best practices”, “should do’s”, “should not do’s”, “readable code”, “naming conventions” and other terms and practices that you may or may not be familiar with. And if at this point you haven’t picked up Robert C Martin’s Clean Code book, this post is for you.
So, what’s Clean Code? – My take: it is code that works efficiently and is fully tested and also that others can read, understand, feel good about it and use it without hassle.
But that’s just me, Robert Martin brings us a few other definitions from well-known and deeply experienced programmers, and among those is Michael Feathers’s:
I could list all of the qualities that I notice in clean code, but there is one overarching quality that leads to all of them. Clean code always looks like it was written by someone who cares. There is nothing obvious that you can do to make it better. All of those things were thought about by the code’s author, and if you try to imagine improvements, you’re led back to where you are, sitting in appreciation of the code someone left for you—code left by someone who cares deeply about the craft.Michael Feathers, author of Working Effectively with Legacy Code
And that’s Uncle Bob’ hook: “…someone who cares deeply about the craft”.
Up to that line, I was very proud of being a programmer and then he raised the bar, now I’m ashamed… because maybe I did not care enough about my code (conscientiously!). So, we’d better keep reading.
Next idea I had heard before: Leave the campground cleaner than you found it. – The Boy Scout Rule. In order to have a better codebase, it is necessary not only to write clean code but to make constant cleanups and improvements. “As professionals,” Bob says “we have no other acceptable choice but to do our best to make our work better over time”.
On the other side of the previous idea is the developer’s laziness. Such behavior will keep rotting the code until it is impossible to change a feature or small function without losing our sleep thinking: what else have we broken?. No team or developer should ever have this kind of concern, that’s why we should always push for best practices and clean code.
What else is in the book?
The book is arranged in a set of 17 chapters starting with easier to understand topics like “Meaningful Names”, “Formatting”, “Error Handling” and “Unit Tests”, whereas more difficult topics are ahead like “Concurrency” and “Systems design”. This mashup of chapters are the result of what Bob says is the School of Thought: curated absolute opinions on each topic gathered between Bob and his compatriots.
Let’s review some of the insights, if code is needed I’ll bring the same code as in the book.
Meaningful Names
Chapter two is all about how to pick a name for a variable, class, or function. We are supposed to write our code in a way that can be read by others like prose. Besides the control structures of our language, all we have are our own classes, functions, or variables to tell us what’s going on. Let see the example in the book:
int d;
What is variable d? – Apart from the fact that it is an integer, we can’t tell more about it. Let improve it a bit:
int d; //elapsed time in days
Now we know what it is! – Well, let’s find this variable again 50 lines of code below:
list.add(d);
Yeah, that’s a list and our d is been added. Wait, what was the variable again? a list of what?
Comments won’t solve our semantic problem, we need to be able to read any line of code and understand what’s going on without the need to go anywhere. We need to pick better and more meaningful names.
int elapsedTimeInDays;
int daysSinceCreation;
int fileAgeInDays;
What about these variables? Do we know what they are? – Exactly.
Same thing for classes, functions, interfaces, and objects. This chapter will teach you how to pick names efficiently avoiding common mistakes. Definitely a must-read.
Functions
Functions should be small! That’s pretty obvious, right? Well, we still find ourselves writing sentence after sentence, we look at our editor and there are 300 lines. What?! – Well, It is long but it works (developer laziness speaking).
Of course, it should work, but it also has to be clean, easy to read, and easy to understand by someone else. Our function should have a single task, do it well and make it clear. Would a function of 300 lines be easy to read and understand? – Probably not, so let’s get to work. We are professionals, we care.
What about arguments? – The less there are the better. As we go along with the book we will find insights that are pretty obvious when reading them, but have we reflected on this before?
Arguments are even harder from a testing point of view. Imagine the difficulty of writing all the test cases to ensure that all the various combinations of arguments work properly. If there are no arguments, this is trivial. If there’s one argument, it’s not too hard. With two arguments the problem gets a bit more challenging. With more than two arguments, testing every combination of appropriate values can be daunting.Robert C Martin. Clean Code.
Unit Test
Good code can not exist without automated testing. Testing is our insurance that the program does exactly what is intended to do and nothing more. Tests are our vigilante, they will let us know if some change is trying to mess with our code and will tell us exactly how to fix it.
Some teams and developers are still struggling with unit testing. “That’s time we don’t have,” they say. They are wrong, code without tests is code ready to break or disciplined bugs waiting for the right moment to do their thing. That time they were saving, they will need it multiplied later.
Uncle Bob is a strong advocate for unit testing and this chapter is all about why you should do it and how. Really helpful reading.
At some point, you will see this acronym in the book: F.I.R.S.T. – Yeap, first time I saw it too. This is about rules for clean unit tests. Let’s list them here:
- Fast Tests should be fast. You should run your test suit very often, slow test will discourage you to run them frequently, or keep writing them as nobody likes to waste time.
- Independent Tests should not depend on each other. Every test should be able to run independently and in any order you like.
- Repeatable Tests should be repeatable in any environment or environment agnostic. You do not want to have a reason like: “Tests are failing because we are not in development“.
- Self-Validating Tests should have a boolean output. Either they pass or fail.
- Timely Tests need to be written just before the production code that makes the test pass. Doing the other way around will cause production code to be very difficult to test as it was not designed to be testable.
Conclusions
Clean Code is a must-read book for every programmer. It introduces the concept of “the craft” or “craftsmanship”. Every chapter will take you to experiments on how things could be better, and how you can be a better programmer.
I always keep it close and navigate the chapters as I need. I do not take its teachings as absolutes, but they are definitely a guiding light on how to be a professional.
Finally, I would love to hear from you, and your experience with the book. What do you think?