Clean Code: Tips, Tricks, and Examples
Does the image above upset you? Or have you suffered from the same fate? Either way, you’ve come to the right place. Most programmers prioritise the functionality of their code, and neglect the cleanliness of it. Then they pass it on to other programmers and inflict a heavy burden on their team.
Don’t be that kind of guy. When we were kids, we were taught to clean up after our own mess. Now that we’re programmers, we should strive to do the same. Here are some tips & tricks on writing cleaner, better code:
Writing Comments
Your comments should aim to clarify your code only when there is no way to do so in code. If you could rewrite your code to make it more understandable, then there should be no reason to write comments. You can use your comments to warn, clarify, or explain your intent to others, but anything more than that should be explained in code¹.
Don’t comment bad code, rewrite it
—Brian W. Kerninghan
Naming
Names of variables and functions should be clear and descriptive. Ambiguous naming will confuse other programmers, and slows down the development process as a whole. You should aim to set names of variables and functions which are pronounceable and searchable¹, in order to aid your fellow programmers in continuing your work.
Also, you should follow the naming conventions of the current programming language or framework you’re working on. So for example, a variable in JavaScript should not be written in snake case, but should rather be written in camel case, like so:
Function Rules
A function should do one thing. They should do it well. They should do it only.
The functions you write should be small, and do one thing. This means that your function should not have any side effects. For example, if you have a function called isEqual(), it should only return a boolean, and do nothing else².
Also, you should attempt to limit the number of arguments your function receives. The best function is a function which takes in zero arguments (niladic), and you should avoid having more than three arguments in a function. This is because arguments are difficult to understand conceptually, and even harder to test¹.
Another rule on functions is that the names of your function should only tell you what it does, not the specific details of how it accomplishes its task. Here’s an example of that:
Exception Handling
You should always prefer to return exceptions rather than error codes². Exceptions thrown should also be clear, providing enough information as to why and where the error occurred. This ensures that you and your team are prepared for the error, and know exactly how to handle it.
You should also not include try-catch blocks into an already existing function, and instead extract it into a separate function. This is conforming with the rule we discussed above. Functions should do one thing, handling errors is one thing².
DRY
This design principle should be common knowledge to programmers everywhere by now, but that doesn’t make it any less important. DRY stands for don’t repeat yourself, meaning that you should avoid code duplication anywhere in your project.
This is opposite to the anti-pattern WET, which stands for write everything twice. You can avoid being WET and stay DRY by applying design patterns, object-oriented principles, and higher-order functions in your project.
Here’s an example of that in react:
Both examples would return the exact same thing, but the second one is much cleaner and maintainable compared to the first.
Layout and Structure
Writing code should be like poetry, it should be beautiful and enjoyable to read (at least for programmers). Hence, the structuring of your code must be neat and clean, in order to lessen the burden you pass to your coworkers.
Every line of code that is related should be grouped together, and other unrelated code should be separated by white space. Also, try to keep every line short, avoid excessive horizontally stretched lines of code¹.
Local variables should also be declared as close to their respective usage as possible, while global or instance variables be placed on the top. Related or similar functions should also be placed close together, and functions that call another function should be placed top to bottom, with the function that calls placed on top of the function it calls².
Conclusion
Remember the picture we saw at the very top? How can we use the rules of clean code we just learnt to improve the situation?
One thing we could do is separate the conditional checks into its own function, or multiple functions, that way the current function only handles one thing, and becomes less messy. We could also apply a design pattern to clean up the mess, but let’s not get into that in this article.
In short, you most likely won’t be coding alone. We need to make sure that our coworkers understand our code as much as we do. Therefore, it is not enough for us to make programs that work, it also must be free of mess and easy to understand. In other words, our code has to be clean.
[1]: Clean Code by Robert C Martin
[2]: https://blog.gojekengineering.com/the-basics-of-writing-clean-code-39ed770b626d
