I recently read 10 tips for writing clean code. After I finished, I did my own thinking on what should I adopt from the article, what am I doing wrong and how can I do better.
Working for a maturing startup company, seeing how quickly our code base has grown, I decided to stitch up some of the things I read with my own reasoning and conclusions, and share my take on how to promote better code quality; building code discipline.
Own it.
The first tip in the article is “You are responsible for the quality of your code”, and rightly so, because it is the hard truth. You. Not anyone else. Not your product manager nor even your TL are responsible for the quality of your code. Neither a nearing schedule nor a pressing blocker are excusable reasons for delivering something that is half baked and/or that you are not positively sure about.
Not sticking to this principle will likely cause you to waste more time than save time by handling the imminent ricochet, forcing you to do the clean up on a later occasion. That later occasion, that is beyond your control, is bound to happen at the most inconvenient moment, when context switching is the most difficult. And even if you did not take the ricochet, and someone else did, then karma will get back at you in one way or the other.
Write what you mean and mean what you write.
Most of the time that you spend in front of the code is by reading it, not writing. You scroll up, you scroll down, jump from this method to that method, move from one file to the next, while trying to find or understand something.
Think about all the times you did just that and then suddenly you bump into that bit of code, and maybe it is the most genius and sophisticated bit of code you ever bumped into, and it may be making a most excellent use of the language it is written in — but you can’t read it. The variable names simply have no meaning and the methods names are far from being descriptive. Confronted with that code, you may be beginning to connect some dots, remember what each variable holds, make out the logical connections and just when everything seems to sit right in place — you are being interrupted; maybe the phone rang, maybe a colleague has asked you a question. Everything has collapsed and even without being interrupted, you dug so deep that you can’t even recall what you were trying to figure out.
Don’t make your code a nightmare for someone else to read. Use meaningful names for variables and methods, make them as descriptive as you can. Put in the effort so that the intent of your code will be clear to the person who one day will read it.
Follow the single responsibility principle.
The chimera is a monster from the Greek mythology, it has two heads, one of a goat and the other of a lion, a snake for a tail and it breaths fire. It does sound like a terrible beast, but I doubt how well this creature functions. Having two (or three) thinking parts, how does it decide where to go? which Hellenic island to terrorize?
When writing a component of code, whether it is a method or a class, be careful not to create a chimera. Each code component you write should have one responsibility, just one thing that it does and it does well. Not following this principle leads your code to quickly become monolithic, hard to maintain and prone to bugs. If you follow the principle of descriptive naming and your method or class does more than it implies it does, then you are misleading the developer that will end up using it. Furthermore, adding more and more responsibility to a single component adds more logic and more code to it — soon enough you are stranded on an island with a chimera and surrounded by a sea of code.
You can see this behavior in methods that are being added more and more parameters over time — this scenario can be corrected by rethinking the purpose of the method, whether should the method be broken into several methods, or should it pass on some of its parameters to other methods. In such case, maybe these parameters can be encapsulated in a way that makes more sense. The same approach applies to methods that seem to return more than one result.
Take another example. Think of a class that both covers many cases and implements these cases instead of becoming a class that delegates the responsibility of each case to a different component.
Leave your code better than you found it.
“Not only should you write clean code, but also take a few minutes to clean up cruft when you find it. Following this mantra means that code can actually get cleaner and cleaner over time.”
This is where I imagine what if Sun Tzu was a developer, how he would have summed it:
When variable and method names are not descriptive enough — make them so.
When you encounter a copy-paste code — Apply code reuse.
When you are faced with a monolithic bulk of code — Break it up.
When you scroll through old code that was commented out — Omit it.
Furthermore, your IDE is an incredible tool, know it well and refactoring becomes easy.
Practice makes best.
“Musicians don’t only play in front of an audience.”
This is a really good analogy. But you must also develop curiosity, learn new techniques and then practice them. And that’s not enough either, look outside your bubble, beyond your R&D bubble even. You are surrounded by technology and tools, some of which are there to make your job easier, some of which are part of a whole with whom you should be familiar. So ask. read. investigate. write. share.
Write tests.
This is where I fail, I must admit it, test-driven development is the last thing I can preach about. But the value is enormous. When many developers work on the same project and the Product team keeps requesting more and more deliveries, the component you once wrote may have to change or evolve. It’s fair and natural. But you don’t want it to unnecessarily lose its original functionality. Luckily you wrote some tests for that component, so you have nothing to worry about, or do you?
Be Assertive. Be humble.
It is important to be resourceful in order to deliver incoming requests, but it is even more important to be assertive when requests have to be pushed back. If the request is half baked or too big and attempting to deliver it may cost in lowering the quality — You may have to learn to say no.
My final note would be that you don’t know everything, whatever you learn today, someone else have already learnt that yesterday, seek the greater and wiser to learn how to better yourself, and pay it forward.