3 Tips for Writing Clean, Readable, and Maintainable Code

When we are starting our careers, we believe we are going to spend all our time writing code. And while that is not false, it is also not 100% true. The reality is that in addition to writing, we are going to read. We are going to read a lot. We might even read more than we write. For that reason, it is important that your code is clean, readable, and maintainable.

Declarative code

Declarative code is code that states what needs to be done, but not how to do it. I know this does not mean much yet, so let’s look at it in more detail with some examples.

Declarative code is based on abstraction. That is, instead of executing certain logic directly, we execute a function that performs that logic, or we create a variable with a descriptive name for that logic. This way, everything becomes understandable at first glance.

If necessary, we can always go and see what the function does in order to better understand that logic. But in principle, the only thing we need to know is what it does, not how it does it.

Let’s look at this code…

if (user.age >= 18 && user.products.length > 0) {
  doSomething();
}

While we can read it and understand it, it would be much easier to understand if we took a more declarative approach…

const isAdult = user.age >= 18;
const isClient = user.products.length > 0;

if (isAdult && isClient) {
  doSomething();
}

This way, we can understand the big picture quickly and then, only if necessary, read the rest.

Comments

Comments are a sensitive topic among programmers. There are many fans of commenting everything and many fans of commenting nothing.

We like to use a hybrid approach. By default, we do not comment anything. We believe it is better to write self-descriptive code. However, there are certain cases where arbitrary values appear or things that simply have to be there and, no matter how hard we try to use good variable and function names, they are difficult to understand for a specific reason. In these cases, we add a small comment explaining the reason for that arbitrary value or the reason why the code is written the way it is.

// Here we would explain why we are subtracting one year from the user,
// something that does not make much sense at first glance.
userAge -= 1;

On the other hand, it is completely correct to assume that our code will be read by programmers. Starting from that premise, comments that describe exactly what the code does become completely useless and redundant. An example:

// If the user is over 18 years old, execute the doSomething() function
if (userAge >= 18) {
  doSomething();
}

Naming conventions

The way variables and functions are named depends on each team. Any approach is fine as long as it is maintained throughout the entire codebase. However, there are some points that I always find interesting to keep in mind.

Consistent abbreviations

Abbreviating is a good way to keep things short, but it can easily get out of control.

To prevent that from happening, there are two things to keep in mind:

• The abbreviation should make sense and be very easy to understand what it refers to.
• The abbreviation should be consistent. If there are two variables with the same abbreviated word, both abbreviations should be the same to avoid confusion.

Avoid double negatives

A double negative refers to when the name of a variable is negative and it is used in a condition with a negation operator in front of it.

Something like this:

const isNotAdult = userAge < 18;

if (!isNotAdult) {
  doSomething();
}

This happens quite often and makes the code more complex to understand.

Simply by rethinking it, everything becomes much easier to read and understand.

const isAdult = userAge >= 18;

if (isAdult) {
  doSomething();
}

Conclusion

All these details aim to reduce complexity when reading and understanding code. And if code is easier to understand, it is also easier to maintain.

Finally, it is recommended to discuss these topics with the team and make sure everyone agrees on following the same conventions.