If you are a developer or planning to become one, see yourself as a chef. People should be able to conveniently eat your food. Also, imagine leaving the kitchen for someone else – another chef should be able to continue from where you stopped – or make the food you cooked earlier taste better. In the same vein, you will be doing yourself, and other developers, a huge favour if you develop a habit of writing a clean, concise, maintainable, and testable code. In this tutorial, we will go through some best practices for writing clean code and provide code snippets to illustrate them.
Use Descriptive Variable Names
One important aspect of writing clean code is using descriptive variable names. Variable names should be meaningful and should describe what the variable represents. This makes it easier for other developers to understand the purpose of the variable, even if they did not write the code. Avoid using short or obscure variable names that do not accurately reflect the purpose of the variable. Checkout an example below:
This code snippet above is not very readable because the variable names do not accurately reflect their purpose. Instead, consider using more descriptive variable names, like this:
Now, it is clear that the code calculates the area of a rectangle with a width of 10 and a height of 20.
Here is another example:
In this example, the function name is not very descriptive, and it is not clear what the function does. A better way to write this code is to use a more meaningful function name:
In this example, the function name accurately reflects what the function does, making it easier to understand and use.
Add Comments To Your Code
While using descriptive variable names is essential, sometimes it is not enough. Comments can be used to explain what the code does and why it is written in a certain way. Comments should be concise, clear, and placed in the right context. Avoid writing comments that are too long or redundant. The comments in this code are clear and provide helpful information to the reader. It is easy to understand what the code does and why it is written in this way. Also, comments should be used sparingly and only when necessary to explain the purpose or functionality of a piece of code. Avoid using comments to explain what the code is doing, as this should be evident from the code itself. Check out this example:
Minimise Complexity
Minimising the complexity of code is important to make it easier to read and maintain. Complex code can be difficult to understand, modify, and debug. One way to minimise complexity is to break down complex functions into smaller functions that are easier to understand and manage. Another way is to avoid unnecessary nesting or conditional statements and to keep the control flow as linear as possible. Check out the example below:
In this example, the code has unnecessary nested conditional statements, which make it difficult to read and understand. A better way to write this code is to use a linear control flow with a switch statement or a series of if statements:
Keep Functions and Methods Short
Functions and methods should be kept short and perform a single, well-defined task. If a function is too long or complex, it can be difficult to understand and maintain. Let us look at an example:
Handle Errors Gracefully
Errors and exceptions should be handled gracefully, with clear error messages and appropriate actions taken to handle the error. Don’t worry if this sounds confusing. I have an example for you below:
ADDITIONAL TIPS
Here are a few more tips to keep in mind when writing clean code. Some of the tips throw more emphasis on what we have discussed already.
Keep Your Code DRY (Don’t Repeat Yourself)
One of the key principles of clean code is to avoid repetition. DRY stands for “Don’t Repeat Yourself,” and it means that you should avoid duplicating code as much as possible. Repeated code can lead to errors and make it harder to maintain the codebase. Instead, use functions, classes, or modules to encapsulate common functionality and reuse it throughout the codebase.
Avoid Global Variables
Global variables can make it harder to understand and debug your code. They can also lead to unexpected behavior and make it harder to reuse code. Instead, use local variables and pass them as arguments to functions or methods.
Document Your Code
Good documentation can make your codebase more accessible and easier to maintain. Use comments to explain the purpose and functionality of your code, especially for complex or non-obvious sections. Use documentation tools, such as JSDoc, to generate documentation from your codebase.
Use Version Control
Version control is a crucial tool for managing changes to your codebase. It allows you to track changes, collaborate with other developers, and revert to earlier versions if necessary. Use a version control system, such as Git, to manage your codebase.
Refactor Your Code
Refactoring means restructuring your code without changing its behavior. It is an essential part of writing clean code because it helps to improve the code’s design and readability. Refactoring can also help to remove duplication, simplify complex code, and improve performance.
Keep Your Code Simple
Simplicity is key when it comes to writing clean code. Avoid overly complex code and aim for simplicity wherever possible. Use straightforward solutions and avoid unnecessary complexity or clever tricks.
Use Consistent Formatting
Consistent formatting can make your code easier to read and understand. Use consistent spacing, indentation, and line breaks throughout your codebase. There are many different styles of formatting, but the most important thing is to be consistent. If you’re working on an existing codebase, make sure to follow the existing formatting conventions.
Some popular style guides for different programming languages include:
Google’s Style Guide: https://google.github.io/styleguide/
Airbnb JavaScript Style Guide: https://github.com/airbnb/javascript
PEP 8 Style Guide for Python: https://www.python.org/dev/peps/pep-0008/
About the Author:
Prince Osinachi Nchiba is a software engineer that has developed edTech and other digital solutions used across Africa. He is a mentor and public speaker with track record of helping young tech talents grow.
