Building Code Discipline
I recently read 10 tips for writing clean code. After I finished, I’ve been thinking on what I should 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 gather some of the things that I read, fuse with my own reasoning and conclusions, and share my take on promoting better code quality by building code discipline.
Own it.
The first tip in the article is “You are responsible for the quality of your code”, and it is 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. I promise you that.
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 that 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 that 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 do follow principles of descriptive naming but 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.
For example, you may see this behavior in methods that are being added more and more parameters over time. Such scenario can be corrected by rethinking the purpose of the method, whether should the method be broken into several methods, or these parameters encapsulated into a context object that made more sense to be passed around. A similar approach may apply to methods that seem to yield more than one return value.
For another example, imagine a class that handles many scenarios, but also implements the logic behind each scenario. This class is long, but it wasn’t so at the beginning, over time it has accumulated logic and grew with responsibilities. Such a class should eventually be broken down by having it delegate the responsibility for each scenario to a different component.
Leave the 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.”
At the time I first read the article I also happened to be reading Understanding Sun Tzu on the Art of War. And so, I imagined what if Sun Tzu was a developer, how he would have summed it:
When a variable or a method name is 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 down.
When you scroll through old code that was commented out — Omit it.
Furthermore, your IDE is an incredible tool, know it well and cleaning and refactoring becomes easy.
Practice makes best.
“Musicians don’t only play in front of an audience.”
I love it, this is a great analogy. But you must also develop curiosity, learn new techniques and then practice them. And that’s not good 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 and share.
Write tests.
Business is booming, the company is growing and more developers are being recruited. Having more hands on the keyboard may help get those features done quicker or in greater volume. But then again, more hands on the keyboard means more changes, changes to that precious component you wonderfully wrote. Changes have to be made, it is fair and natural. But how do you ensure that that component still does what it should do? How do you communicate the contract of expected component behavior to the next developer that will work on it? Luckily you wrote all those tests that ensure just that, so you have nothing to worry about, or do you? you did write those tests we were talking about, right?
Be Assertive. Be humble.
There are several qualities that are good for a developer to have. I usually look at resourcefulness — how well does a developer manage when they don’t have all the information and resources. But it is also very important to be assertive. When a deliverable is half baked, too big or risky to such a degree that attempting to deliver it may cost in lowering quality, then it may have to be pushed back — You will have to learn to say no.
Finally, no one knows everything — in fact, the more you know, the more you know you don’t know — whatever you learn today, someone else has already learnt it yesterday, seek out the ones around you — they don’t have be greater or wiser — to learn how to better yourself, and most importantly, pay it forward.
