Code for Humans
I have been studying on the topic of writing better code for a few months now and have attended some workshops/sessions by various thought leaders on the topic and the thing that comes out strong in every one of those is the need to write code for humans [the machine will anyways perform the instruction given to it]. The basic idea of being agile, continuous delivery and improvement also stresses on the fact that the underlying code that makes up the system also needs to undergo change continuously.
So, I asked myself, how do I code for humans? I think there is no silver bullet to this but is actually based on the team's appetite for the same, but some pointers that might help you are as below,
- Use appropriate naming for classes, methods and attributes. Do not name then as an obfuscator would.
- Use Single Responsibility Principle, let your functions perform a specific task. Also consider limiting the number of variables passed to the function.
- Do not repeat yourself, whenever you feel that you are repeating yourself try to refactor it into a reusable module/function.
- Use of comments, and I do not mean to start a debate on this; it is just another tool to ensure that the idea behind the code that has been written is understood by anyone in the team. you do not have to over comment but be reasonable to comment where ever you feel that your tech decision needs to be conveyed in the code.
Continuous Improvement in a product also requires code blocks to evolve over time and you may or may not have the same team to work on it. Ideally you should spread the knowledge of the software across multiple contributors/teams.
And you will also agree that it is a lot easier to debug code which is written cleaner than dirty code, saving you time to focus on fixing the bug rather than first understanding what the code written actually does by going through the entire piece debugging.
Do let me know your views on the same.
Godspeed.
Disclaimer: the views and opinions expressed above are solely derived from my personal experiences and does not represent my employers or anyone else’s.
very good article sir... such a practice always helps to understand the code quickly and implement new addition/change with ease...
Agree with S Siddharth RoyChoudhury .. in the long run I have found a few more things that seem relevant . 1) writing comments is not a good idea.. people update the code but usually forget to update the comments.. so code alone is the source of truth .. same goes with javadocs or any documentation .. 2) what helps in the long run is a very rigorous code review process .. the fact that a developer has written a clean code can only be verified if others are reading the code and they are understanding it . 3) in the long run .. one of the way to avoid code smell is to keep refactoring the code and have updated test cases .. orgs which follow tdd tend to change their code often and can do it using the safety net of tests .
The book clean code by Robert C martin emphasises this exact same thing and many other pearls like naming conventions, function length, no of args in a fn, handling if else, using test cases first approach etc... give that a read as well
Yes this will help a lot when project is on maintenance stage 🙏🙏
Mrityunjay Mukherjee Very good thoughts especially in the context of CI/CD. Not just write clean but also "secure" code 🙂