Matchbox and Coding Standards

Have you ever performed a code review that looks like this?

Not a single logic change. Not a single new feature. Not a single deletion. Only code format changes:

• A comma at the end of an Array
• Parenthesis enclosing the parameters of an arrow function.
• Two spaces where there used to be 4

This is a sign of a lack of coding standards in your company or team, which is not good. In cases like this, the reviewer can get overwhelmed by the sheer amount of changed files, and code style changes can obscure the ones that really need attention. They can miss a logic error while lost in a sea of red and green.

Code style changes are just noise. They should not exist. An ideal code review diff must be clean. It should only have real and important changes like new logic, new features or deleted code:

This diff shows only new code and structural changes. This is ideal.

But how can you ensure there’s only important changes in your pull requests?

Enter Prettier.

Prettier is a tool that formats the code for you. In its simplest usage, you run a command for a folder or a file and it formats their content. But there are better ways of doing this like formatting automatically when you save on your editor. But we wanted to go a step further. Now an unexpected turn.

Enter ESLint.

ESLint helps you identify possible errors in your code. It’s the perfect first line of defense against bugs. A recommended practice is to install an ESLint code editor extension like this one for VS Code so you can see directly in the editor the exact line where the error or warning is occurring.

But simply using Prettier and ESLint is not enough because every developer can have different formatting or linting rules that adapt to their taste and preferences. Or, in the worst case, they could not have any. What you need to do is define and enforce a set of rules for everyone in your team or even better, everyone in the company. We did exactly that in Condor Labs and now I’ll explain how we did it.

The Process

The rules

First of all you need to define a set of rules for each tool. For this we created a little committee with people from the Technology department and representatives of the Product teams. First the technology people defined an initial set of rules that were later discussed and adjusted by the committee in general.

After the rules were defined and agreed upon by the committee, we needed a place to store them. We didn’t want to distribute the configuration files because updating the rules would be extremely cumbersome. We needed a centralized place for them.

The centralized place

We chose NPM to store them because when we need to add or remove rules we just change the file in one place, update the new version and the teams will just need to update the NPM package and nothing more. Easy. We created an NPM package for the Prettier rules and one for the ESLint rules.

Now we needed a way to monitor the usage of the rules packages. Also, we wanted this process to be delightful, fast and easy. For that we created a script and uploaded it to NPM.

The script

We created yet another NPM package that performs the following tasks:

1. Installs itself so we can monitor what version each team is using.
2. Installs the NPM package with the Prettier rules.
3. Installs the NPM package with the ESLint rules.
4. Creates a Pre-commit Git hook to run both tools. For this we chose husky and lint-staged.
5. Creates a CODEOWNERS file to control who can modify important files.
6. Installs all dependencies for the previous points to happen.

When you run the script you can choose between JavaScript or TypeScript, depending on your project. This defines different ESLint rules. It also asks you for folders or files to ignore. Here you should type “node_modules” and all folders and files that are automatically generated, in other words, files with code that you didn’t write.

As a rule of thumb: If the code was generated by some tool or build process, don’t analyze or format it.

The packages

In total, we created 3 NPM packages:

• prettier-config: This contains the set of Prettier rules.
• eslint-config: This contains the set of ESLint rules.
• matchbox: This contains the script that installs and configures everything.

The results

We have implemented Matchbox in several of our projects and in each one of them we discovered thousands of warnings and errors thanks to ESLint. We also standardized the code format with Prettier.

We also recommend that you apply this configuration in two phases. First run Prettier and create a Pull Request. Depending on your project, you could have hundreds of changed files. This Code Review should be fairly fast because no logic changes are introduced. You can approve it at once if you want. For this you need to disable prettier in the pre-commit hook.

Then activate the linter and work on the warnings and errors. This code review should be taken more seriously because it contains manual changes done by developers that might affect the current logic of your application.

The conclusion

Here are the main takeaways:

• Define a set of Prettier and ESLint rules for all the teams in your company.
• Define a centralized place to store them.
• Define a way to control and enforce the usage of those rules.
• Make it extremely easy for developers to configure the necessary tools.

By using matchbox you can save the effort of doing all this.

What’s next?

Lines can be commented. Tools can be disabled. In order to ensure that the code is formatted correctly and that no linter warnings or errors exist in the code, you can add these verifications in your CI/CD pipeline. This is the next step for us.

If you want to use matchbox you can find how to run it and everything you need to know in the NPM package page.

Thank you for reading!

This is a series of articles that talk about code standardization and good practices for development teams.

The next one will be about implement Matchbox in a CI/CD pipeline.