So you think your code is clean?
What does it mean to have clean code?
“Any fool can write code that a computer can understand; good programmers write code that humans can understand.”
While getting ready for this post, I came across the interesting quote above, which is by Martin Fowler. Have you ever come across a piece of code and you’re like “Oh my God! What was this individual thinking when writing this code?” And then you take a step back and decide to use a tool like GitLens to check who wrote the code. For those who don’t know, GitLens adds authorship to a file and even to lines of code. In other words, you’re able to easily see who to blame for any piece of code written. So yeah, with the GitLens extension, you decide to find who wrote the inferior code, and alas, you discovered that the code was written by none other than you. What do you do at that point? Are you one of those that act like nothing tragic just happened and move on? You are not alone.
In discussing clean code, we’ll be looking at how to make your code clean and this simply means making your code readable, ensuring that you’re not that person that comes across code they’ve written three months prior, and do not believe that they wrote it.
Why do we need clean code?
As we saw from that quote by Martin, great code is written for regular human beings — not superhumans, ex-men, or supernatural beings — to understand. Because of this, it needs to be as clear as possible. This means that in ensuring that your code is clear and easy to understand, people need to be able to read and understand it in a short period of time. You also need to make it easy for someone else to maintain it down the line. They should easily be able to refactor without incurring technical debts.
Practices that make code readable
- Good variable and function names
Firstly, the typical and most common practice is poor variable and function names. When creating variable and function names in your code, avoid using acronyms as much as you can. For example, if a variable stores the lines per page in a book, using “lpp” to denote lines per page is bad practice; so is using “upi” to represent user profile information.
On top of that, one thing people sometimes do is represent variable names with single letters, e.g x or y. This is hard for any reader to understand at first glance, or even at a second or third glance.
Try to stick with using a name that easily shows what that variable is responsible for. It’s funny because it can really be hard to come up with names. I’m so sure that people that have kids probably spend months deliberating on what names to give their kids. I know it took me a while to give my Wifi a name. It took some deliberations and thinking. And eventually, the name I came up with was not even up to six letters.
- Single-responsibility of functions
Having a function that does too many things causes ambiguity in code. A function doing more than one thing needs to be split up — break it up. If your function needs to add numbers, it should be taking the necessary arguments and only adding them. You should not be sending emails in a function that should only update user input fields. I know it’s tempting to have a longer function sometimes, but if it means that it has to handle two or more different responsibilities, then it’s so no worth it. Also, if your if-else statements are beginning to get too nested, it’s time to start thinking about splitting them up into functions.
- Documentation
It is important to look out for comments and documentation in a codebase. A general thing is to check that you don’t find yourself explaining what your code does with comments. Now, when you begin to see this happening, you want to take a step back and look at it again. Your code needs to speak for itself — not the comments. Your comments should ideally explain the reason something is being done, and not what is being done. Also, try to ensure you don’t have stale comments. When the code is changed, update the associated comments. Leaving stale comments on updated code can be misleading. You also want to make sure that your readme file describes how the codebase is set up, and other vital information. And you want to ensure that this is updated frequently as it will be super useful for new developers joining the team, or even another developer on a different team, who just cares to know what’s going on on your team.
- Indentation
One major thing to make your code easily readable and pleasing to the eyes of the beholders is indentation. Lots of tools out there are available to automate this. I personally use Prettier to keep my indentation nice and clean. So you might want to take advantage of this as well.
- Tests
You want to write tests that keep your code accountable. It basically helps a reader seeing the test to know how the code should function and what is expected of it. It’s also useful if you need to update some parts of the codebase. So if you had tests written for those parts, the tests will obviously fail because they no longer meet the criteria for the new updated code. So you see why it keeps your code accountable. Ideally, the TDD (test-driven development) process is advised.
- Practise
Finally, practice practice. Learn by doing. The more you write and view other people’s code, the better you are at identifying and writing good code.
