JavaScript Refactoring: 5 Plays to Improve Code Quality

No code is perfect, and nobody writes the perfect code. That’s why I’m writing this post. If everyone wrote absolutely…

By Testim,

No code is perfect, and nobody writes the perfect code. That’s why I’m writing this post. If everyone wrote absolutely perfect code all the time, there wouldn’t be a need for this post.

So how do we improve the quality of our code? One approach is to refactor the code.

But what exactly is JavaScript refactoring about? Refactoring includes many elements, such as:

  • Writing clear, understandable, and maintainable code.
  • Writing meaningful comments and error messages.
  • Sticking to standards like naming conventions and code structure.
  • Modularizing chunks of code and how to structure those modules.

As you can see, JavaScript refactoring includes many elements. Additionally, it’s not an exact science. Still, let’s try to improve the quality of your code. Let’s dive into five tips for improving code quality.

1. Commenting

Not everyone is gifted at writing clear comments. However, communication (even if it’s textual) is important.

When you write a piece of code, always develop the code from the standpoint of the next person who will work on the code.

Code changes all the time—so will yours. There will always be an occasion where another developer has to make changes to your code to fulfill new business requirements.

Therefore, you must spend time making sure your code is understandable. In my opinion, adding comments to your code always adds extra value. Although the code itself should be easy to read and understand, having extra explanations of a function helps the next person working with the code quickly grasp the purpose of a particular function.

So, how do we comment?

How to Comment Meaningfully

Generally speaking, there are two types of commenters. Some developers prefer to be very verbose, whereas the other type add very few comments.

A snippet of code that’s bloated with comments is hard to read. We want to avoid bombarding fellow developers with too many code comments. However, minimal code commenting often adds little value.

So we need to balance both the number of comments and how we describe things. Sticking to some easy-to-use standards helps you accomplish this goal. Let’s explore the following three comment types: top-level, class-level, and function-level commenting.

Top-Level Commenting

A top-level comment should give the reader an initial explanation of the purpose and responsibilities of a file. A two or three line comment is sufficient to give a fellow developer a clear indication of the purpose of the file.

Class-Level Commenting

In order to understand the need for a certain class, a developer should add a short description to each class they define. A class-level comment should include details about:

  • Goal and scope
  • Usage
  • Location in the bigger architectural picture

Function-Level Commenting

Last but not least, function-level commenting focuses on making the purpose of a function clear. Function-level comments should, for example, describe how the function converts input to output or explain the business logic.

A good reference for writing function-level comments in JavaScript is JSDoc. JSDoc tries to define a standard for commenting.

JSDoc itself is made up of a markup language that uses annotations to annotate JavaScript code. Using those annotations, programmers can add documentation in a structured way describing their code.

Let’s assume we’re working in a class Point that has an X and Y coordinate. The following fromString function converts two comma-separated numbers into a Point. The comment nicely describes what the function does. Besides that, it describes in a standardized way the expected input with @param and the return value with @return.

JSDoc is definitely worth checking out to bring a more standardized approach towards code commenting to your development team.

2. JavaScript Refactoring According to Standards

There is no doubt that standards help to improve the quality of code. It’s important to check for those standards while refactoring your code.

Of course, every language has its own set of standards you can decide to follow. Let’s explore some commonly-used naming standards for JavaScript.

Naming Arrays

An array often contains a list of items. Therefore, we prefer to append an s to the variable name. If a developer reads code or looks at the interface of a function, they immediately know that a variable that ends in s is most likely an array.

Naming Booleans

For Booleans, we want to stick to natural language.

For example, we want to know if a car has a license plate. The result is a Boolean, so we name the variable that holds this Boolean hasLicense. To give another example, we want to know if a person is sick so we use isSick.

Both is and has are commonly used prepositions to indicate the variable holds a Boolean.

Looping Arrays

Last, keep things simple when naming variables for looping arrays. Let’s take a look at the below example, which takes a car out of the cars array:

Use the above conventions for refactoring your code. These standards help you to make your code more readable.

Want to spend less time refactoring tests? Take a look at Testim’s self-maintaining tests that use machine learning.

3. Meaningful Variable Names

A name should be descriptive and tell a fellow developer what it holds.

For example, what if we want to store the number of days that have elapsed? We could a simple one-letter variable with a comment. Of course, that’s a bad practice.

To further improve the naming of this variable, let’s try using elapsedTime. Again, this is not a very good naming as it does not reveal the type of the variable.

Finally, let’s try one more time using elapsedTimeInDays. This name is much better as it indicates the variable holds a number and explains what the number represents.

Next, let’s look at how to handle errors.

4. Returning Errors

While refactoring, it makes sense to read every error message carefully. Does the message describe the exact reason for the error? Let’s take a look at some bad examples.

Ambiguous Message

Assume we try to log in to an application, but our login attempt fails. The application returns “You can’t log in to the application.” This message is not descriptive enough. It can refer to many possible errors: system down, wrong username, or no access to the application.

Try to return a clear error message, like “Password doesn’t match username.”

Avoid Technical Jargon

Finally, as a user might receive an error message, avoid using technical jargon. Try to explain what went wrong in plain language.

Let’s say the application lost connection to the server:

Good: “Network connection is lost.”

Bad: “Error with code N-23 occurred. Operation could not be completed.”

At last, let’s take a look at the power of modularization.

5. Modularization

When refactoring code, you should spend time analyzing the structure or hierarchy of the code. The structure of code can give us valuable information as well.

For example, we often define a utils file that holds all kinds of shared logic. Sometimes, I’ll make a mess by combining non-related functions.

The presence of a utils file is actually a code smell. Try to group functions into meaningful modules.

To give an example, a file full of util functions contains two functions: add and subtract. Both functions perform mathematical operations. We can easily group them into a Maths module which exposes both functions. Now, when screening the architecture, it’s more apparent where to find those functions.

Refactoring Is Fun

Once you’ve figured out what standards you want to follow, refactoring should be fun. The more you refactor code according to your standards, the easier it is to detect mistakes.

Refactoring definitely helps you to improve the code quality. It makes variable names more clear, describes functions, or returns more meaningful error messages. All these small things make up a better product. Good luck with your next refactoring adventure!

This post was written by Michiel Mulders. Michiel is a passionate blockchain developer who loves writing technical content. Besides that, he loves learning about marketing, UX psychology, and entrepreneurship. When he’s not writing, he’s probably enjoying a Belgian beer!

Testim's latest articles, right in your inbox.

From our latest feature releases, to the way it impacts the businesses of our clients, follow the evolution of our product

Blog Subscribe