How did reading "Clean Code" improve my way to code? — CodeCraftsmanship #1
A long time ago, I finished my engineering school in computer science. Then I started my job as a developer. I was following best practices learned at school like unit tests, renaming, patterns, algorithms optimizations, architecture, refactorizations, modeling, comments, documentation, etc. All the best tools like eslint and prettier were installed in my projects — I am working as a frontend developer. I thought I was a good developer.
A disturbance in the Force
I worked like that for 4 years. During this time I was always feeling something wrong in my way to write code.
Small vs Big dreams
First of all, my way of writing code was not in line with my agile methods. Following agile methods, I should work in small iterations only. But in engineering school, you are trained to write your code perfectly the first time using modelization, patterns, and big plans.
9-months project is a new project
I considered myself a not-so-bad developer. Most of the time I can understand sophisticated algorithms. But while coming back into a project left 9 months before, the code was so hard to understand.
Outdated documentation
Following the practices I was taught, I was always writing comments and documentation to explain my code and architecture. But it was actually outdated just a few days after written.
The revelation
Then I hired a senior freelance in my company and this guy showed the book "Clean Code" by Robert C. Martin. And it really changed my way of coding— Colin, if you read this article I can just thank you a lot 🙏.
This article won't be an exhaustive list of best practices extracted from the book “Clean code”. It will just list few paradigm changes inspired by the book and how they impacted my way to code. So don’t take my article as a guide but more like an introduction to push you to read the book. Besides, when you read and practice "Clean code" in your working days, you may notice that despite the name attractive for all developers, the author proposes in fact an approach very opinionated with benefits and disadvantages.
But from my experience, in the opposite of other methods which often bring more constraints and complicated solutions, "Clean code" bases the rules on simple observations and easy-to-understand solutions — even if you might need a lot of experience to really apply them.
Code is specification
When you work as a developer with a minimum of organization, you should have a product owner/designer with a list of specifications. We often think that code is the delivery of specifications. But in fact, product designers just write requirements but you can't ensure a full synchronization between the expectations and the reality. So in the end, the only exhaustive Grand Truth of your product capabilities aka the ultimate specification IS your code. Following this logic, features should be readable in your code like crystal.
Several tricks exist to help you make your code more readable.
Segment the level of complexity
Code quality inspectors like SonarQube or Eslint have indicators described as cognitive complexity. It naively describes the number of intricated conditions, loops, etc. According to the global practices, you should keep your code with a maximum of 2–3 levels of intrications in the same file. If you have more, you should hide some complexity in subfunctions and so on. And it is a good start.
But if you want to make your features really easy to read, you should go further. You should split your code into different levels of reading. So that the higher levels have the features readable by your product designer or the marketing guy, the programming language syntax apart.
As an example, if we imagine a function to compute a total price in an e-commerce website given several options:
In line 6, we see the principle of ids that is only useful for developers. In line 16, we see the use of Math.ceil .These lines require more skills to be understood so they should be hidden in sub-functions. So we can then get this version:
Now with the version above, lines 1–19 are understandable by your marketing guy. You keep the sub-functions for more advanced readers.
You can also notice we have no problem creating functions used only once.
It was a small example but I hope it helped you to understand the concept. This kind of segmentation allows everybody to understand the global features and up to the developers to go deeper to understand the details of each feature. It feels easy but from my experience, only a few developers really achieve this leveling.
Prefer few duplications to over-engineering
As an engineer, we are trained to detect and avoid duplications at all costs. We prefer to automatize and generalize everything. In the theory, it is a good idea. But sometimes, it splits the code between configuration files and a big and messy engine. High-level features in configuration files are easy to find. Low-level features in the messy engine are hard to read. You should be careful to make diving from high-level to low-level features very easy so that developers can very quickly understand the details of each feature.
For these reasons, when few features are sharing the same sub-features, it may be more beneficial to duplicate a few lines of codes instead of building an over-engineered generic system.
Prefer readable code over documentation
As said above, it is very hard to maintain documentation. Except if documentation is delivered (like API documentation), I suggest using it with parsimony. For developers, good documentation brings less value than good code. It also costs more time to maintain. So you should focus on writing a code that doesn't require documentation. Easy to say, harder to do but it should be your goal.
Write slower, Read faster
Very often, developers design their code architecture so that writing new code is fast. But in fact, developers spend more time reading code than writing code. So while adding new lines of codes, you should focus on making your code very easy to read, not fast to write. Every time I write a new feature, I read my code dozens of times to optimize it before pushing it to the team.
Code for dumb people
In the past, I was coding so that I could read and understand my own code. I was considering myself a good developer and thought other developers should be smart enough to understand my code. In the reality, it was hard to understand my own code, 6 months after. So now I write my code to make it readable by a 10-year-old child. This way my code is easier to read for all my teammates and also my future me. It also makes my code faster to read and more robust to misunderstandings and so less buggy. Follow this best practice and you will see: your future yourself will thank you.
Agility is also about code
Agility comes from an observation: the world is moving very fast. So fast, big plans have more chance to fail than to succeed. Working step by step and validating each step is the safest way to avoid working for nothing. And this observation can be applied at every stage of a product: design, development, release, sell. So agility is not just about the way to deliver your product periodically to your client. Agility should transcend all parts of your team: the way to deliver, the tools you use, and also the way to code.
Less is More
The best is the enemy of the good as Voltaire said: you should consider coding only the feature you need to deliver during the sprint. Developers often write their code architecture perfectly according to long-term plans even if it is over-engineered according to the current features to implement. Except in very stable projects, the chance to have your requirements changed dramatically before 6 months is very high. So coding for the long term is not a good idea and will just make your code big and so hard to maintain. Besides, even a very studied architecture may not be easy to read at the end because it is so large. So just use the architecture good enough for the current feature. And write it a way it is very maintainable and adaptable to introduce more sophisticated features very fast.
For senior software architects, this solution may look very time-consuming because we often think it is faster to make big changes in one time than small changes step after step. But very often, because of a lack of information and strategic changes, you don't go in a good direction from the beginning. Following the Figure below, working without intermediate validations may cause going to a point C instead of point B and so outside the scope.
Forcing yourself to think small and code small allows you to have short-term results and short-term ways to test your results which are compliant with Agile methods.
Think Big, Act Small: sometimes thinking big will help you to avoid big mistakes so never hesitate to think long-term even if you code short-term.
No perfect code: just a code adapted to a team
As an engineer, you are also trained to analyze code and imagine the best code ever. Perfect code doesn't exist. The only goal of your code is to achieve the feature and be readable by YOUR team and maintainable by YOUR team. As your team is evolving, your code is also evolving with your team. For example, as soon as a new member arrives in your team, your code may slightly change to follow the level of skills and the vision of the new teammate.
Besides, if you find some code no more easy to read, do not hesitate to clean it. The "Clean Code" book uses the term of the boy scout rule: you should leave your code cleaner than you received it.
There is one rule. The rule is: there are no rules.
So far, I described to you a lot of rules I am following but in fact, the most important one is: never be stubborn about rules and adapt them, make exceptions when you need them. Sometimes I authorize a duplication. Sometimes, I authorize mid-term plans to go a bit faster. Sometimes I even allow pushing code without tests 🤯. Agility is about always adapting yourself to new challenges and bringing better value to your users. The main point is just to make the difference between the main methodology and exceptions.
Try your best and always try to improve your methods.
Conclusion
In the past, I was coding like an engineer, following only validated methods and designs. I was considering code as a science. For now 3 years, I changed and now I consider code as craftmanship. I keep my engineer mind to analyze deep problems and for very mathematical algorithms. But I consider the quality of the code as more important than anything just after the customer delivery. So I avoid writing documentation. I avoid making big architecture plans and prefer going step after step. And I code for dumb people. It may look easy but it requires in fact a lot of experience.
In the end, my code is now far easier to read even after several years. It is faster to introduce new features. And I am not scared when we need to introduce big changes because I know our code architecture is ready for any changes.
When I ask developers about this book, a lot of them know the title but only a few of them have really read it. So even if you think you are a good developer and you code clean, if you are experiencing the same issues I was experiencing a few years ago, I really suggest you read the book "Clean code". It might change your way of coding.
Did you like this article? Remember to clap 😜 !
