In this article, I present five principles for improving code readability. These principles are based on my experience on various projects, teams, and organizations. I hope you learned something from this article to make your code more readable.

Too long to look at the version

There are always people who don’t like to read the whole article from beginning to end, but want to get to the point quickly. Here’s a long version of this:

  • Reuse content that will be used many times.
  • Avoid having a one-size-fits-all solution for readability and maintainability.
  • Minimize the size of modules, classes, or components.
  • Enforce rules and guidelines for automating your code.
  • Even if you’re the only one on your team, write collaborative code as if it were a multi-person team.

1. Reuse content that will be used many times

Most developers know what D.R.Y. stands for (avoid duplicate code). D.R.Y. can help you prevent code duplication. Why write a function over and over again? You should only write it once and then reuse it wherever you need it. And if you need to change its code, you only need to change it in one place, instead of copying and pasting the wrong version everywhere. But note that the D.R.Y. principle lets you introduce complexity. Because eventually, things get reused more and more. When you start making changes to code that is being reused many times, the importance of writing tests for that code becomes clear.

2. Avoid generic solutions for readability and maintainability

Reusability, readability, and maintainability are each other’s friends and enemies. When you start practicing D.R.Y. principles in your own code, you introduce complexity. When you introduce complexity, the readability level may go down. Therefore, don’t start with a generic solution when building functionality. It’s best to start simple! It’s not going to be perfect on the first try. With multiple iterations, you can reuse many parts of your application while still maintaining good readability and maintainability. When you work in an organization with many development teams, your team may be split between insiders and outsiders (such as freelancers or consultants). So in this situation, people often switch back and forth between different organizations. In these scenarios, readability and maintainability are key to success. It is not a wise choice to have people who are likely to leave the team at any time to develop common solutions. In some cases, you do need access plans, but they must be easy to read and maintain.

3. Minimize the size of modules, classes, or components

When you’re building new features for an application, you might want to do some planning before you build. The best solution is definitely one that can be broken down into many smaller modules, classes, or components. Do you want to know why? Because smaller pieces of code are easier to test and maintain. Imagine that when you build a tall building in real life, you build it from smaller units, rather than building the whole building at once and trying to install it on the foundation. Of course, there are exceptions. Most modern libraries and frameworks are broken up into smaller building blocks rather than packaged into a single file. JavaScript libraries and frameworks like Angular, React, and Vue adopt the concept of components. I don’t think their choice is an unconscious result.

4. Enforce rules and guidelines for your code automation

To write readable and maintainable code, focus on the architecture of the code on the one hand and the style of the code on the other. I think many readers have often seen discussions about tabs or space indentation. But I’m not going to talk about that here. No matter what solution you use on your team, make sure all team members follow it. The best solution is to automate these code style rules and guidelines as much as possible. Many ides integrate this functionality, or you can install it through plug-ins. The simplest, and one that supports multiple languages and code editors, is EditorConfig. These rules can be applied by simply adding a. Editorconfig. You can adjust many Settings for your project in these files. You can also specify global Settings or language specific Settings. Such as:

  • Indent style: TAB characters or Spaces
  • Quotation marks: single or double quotation marks
  • The maximum length
  • Character set
  • And there’s more…

Here is the configuration I specified in one of my projects:

# Editor configuration, see https://editorconfig.org root = true [*] charset = utf-8 indent_style = space indent_size = 2 insert_final_newline =  true trim_trailing_whitespace = true [*.ts] quote_type = single [*.md] max_line_length = off trim_trailing_whitespace =  falseCopy the code

There are also many tools available on the Web for specific languages. For JavaScript, I like to use Prettier, but you might want to use something different.

Either way, it doesn’t matter which solution is used as long as everyone involved in the project follows the same rules and guidelines.

5. Code as if you were in a multi-person team, even if you were alone

Last but not least, always write collaborative code as if you were in a team! I can imagine that developers who have never written code on a team will have a hard time understanding this principle. But if you’re working on a project alone, it’s easy to write a lot of code that only you can understand (e.g., vague variable names, two or three character variable names, etc.). Try to write code that others can understand just as you would in a team. Imagine that this means your code should be clear enough that others can easily understand it. Ask a friend, or ask someone in the developer community via Twitter to check the readability of your code, which is an easy test. I can guarantee you will get feedback you never expected. Don’t worry about negative feedback! Just pay attention to feedback that makes your code more readable to others. You should be aware that there is no clear line between readable code and code that is a little hard to read, and different people will have different opinions on this issue. If someone tells you that your code is hard to read, don’t feel bad! You should be grateful for the feedback.