Best practices for writing clean code

The principles of clean code have been derived from decades of experience by some of the world's most renowned software engineers. This article will focus on techniques for writing code that is easily understandable for your team members, yourself, and other developers.

We'll delve into some of the most common pitfalls when writing code, especially as projects become larger and more complex. The advice in this article comes from many years of experience working with high-quality codebases at companies like Google and Intuit.

Commenting the code

Comments are often overlooked as a useful tool for writing clean code. The best comment is a well-written sentence, but comments can provide added context to the code that might be lost if the code isn't understandable. Comments can also be used to document code.

Ideally, you want to write clean, self-documenting code, but a complete set of well-documented code can take a long time to create, if done correctly. If you're working in a codebase that lacks good documentation, comments can be a quick and easy way to add valuable information about your code.

For example, if you have a specific business rule to calculate a value in your code, you should add a comment explaining the rule so that the next developer who needs to modify the code clearly understands how it works. You should also comment out other elements of your code, such as function logic, the use of variables, and conditional statements.

Don't repeat yourself (DRY)

The DRY principle is a common principle in software engineering and applies to writing code. DRY stands for “Don’t Repeat Yourself.” It means you should avoid duplicating work in your codebase by creating reusable code.

Duplicating code throughout the codebase is a bad practice. Not only does it lead to a codebase that is messy and difficult to read, but it also makes it more difficult to modify and extend the code. A clean codebase contains a single copy of each component, with the appropriate inputs, outputs, and functionality.

If you find yourself trying to solve a problem in one place, and then having to go back and solve that problem somewhere else, you need to find a way to DRY up the code. If you have a single piece of code that's reusable, you can use that component in multiple places and avoid duplicating code.

Single Responsibility Principle

This is one of the most important principles of software engineering, and it's the foundation for writing code that's easy to understand and maintain. The Single Responsibility Principle states that each component in your system should have one and only one reason to change, and that reason should be obvious.

This means that each component in your code should have a single responsibility—a single purpose. If a component in your code has more than one purpose, then that component should be divided into smaller components with a single purpose. The most common example of this is a function that performs more than one operation.

Whenever you write a function or method, you should ask yourself what exactly that function does. Does it perform a single operation? If it does more than one thing, then you should consider splitting that function into two or more smaller functions that each perform a single operation.

Use descriptive variable names

Another best practice for writing clean code is using descriptive naming conventions for variables. Variable naming conventions are important because they help readers understand the purpose of a variable or function in your code.

For example, if you use the variable name “i” to represent an index in a loop, a reader of your code will know exactly what that variable represents without having to consult comments or documentation.

You should use conventions that make sense for the type of data you're storing in a variable. For example, if you're storing a date in a variable, "date" is a good choice for the variable name. If you're storing a user's name in a variable, "name" is a good choice for the variable name.

Write simple code and continually refactor

When writing code, you should always think about how to write it in the simplest way possible. You should strive for code that's easy to modify, easy to extend, and easy to read.

In fact, you should constantly refactor your code as you write it. You should write a few lines of code, then take a few minutes to clean up your code and make it easier to read. If you do this while writing the code, when you come back to it later, it will be easier to understand what the code does because everything will be written in a single, straightforward way.

This continuous refactoring will help you write code that is easier to understand now, and easier to modify and extend in the future.

Error management

It's preferable to throw exceptions instead of handling them in code. Exceptions are clearer and more maintainable if we work with aspects (AOP), and exceptions can be easily handled if we do.

It's crucial to record what happened in the log and to fail as quickly as possible so we can see what's happening and why more accurately. We can contextualize errors and add clues to help us understand why something failed, even if we can't reproduce the data.

When working with external APIs or libraries, we should catch their exceptions and wrap them in our own exceptions to avoid coupling. This way, our code will be better prepared for future modifications.

Conclusion

The best practices for writing clean code discussed in this article are applicable to most programming languages. If you're new to programming, or if you want to improve the quality of your code, you should make an effort to learn these best practices and incorporate them into your code.

The most important thing to remember is that writing clean code is an iterative process. You won't be able to write code that someone else can understand the first time you try. It takes time, patience, and a willingness to learn from mistakes.