bene : studio is a global consultancy, helping startups, enterprises and HealthTech companies to have better product

Is well-formatted code important today?

December 21, 2020 - Krisztián Csepregi, Dániel Fodor

At bene : studio we love knowledge sharing to help the community of professionals. With 10+ years and over 100 projects behind us, we have a vast amount of experience. This is why we have launched a knowledge base on our blog with regular updates of tutorials, best practices, and open source solutions.

These materials come from our internal workshops with our team of developers and engineers.

Pardon the interruption, we have an important message!

We are looking to expand our team with talented developers. Check out our open positions and apply.

Codes are read by humans as well

Software developers on a daily basis do these things: write code and read code. Surprisingly, the latter is more common, and even reading code can be split up into two main categories. We can differentiate between understanding what we wrote by ourselves and what others have written. There is a reason why I said ‘understanding’; of course a programmer understands what he/she is writing at the time of development. The question gets more meaning when we introduce code maintenance, which means dealing with old code. In the context of using programming languages that could be written anytime from a few months to a couple of years ago.

Well formatted and good code is almost like art. Any developer can write code, but not everybody can present it to others in a readable and understandable way. Reading it is not different from reading a story. Have you seen any book, where each word is placed under each other? The content is the same as it was written in a regular way, but understanding is harder. Like this:

Once
upon
a
time
there
was
a
story
which
somebody
wrote
like
nobody
ever
before…

It is the same with coding. You probably know that all compilers/interpreters could “understand” code if it was all kept in a single line. But the thing is, we are not computers, as I said, we are reading code and writing code, thus it is very important to have every programming language well-formatted for “human-friendly” development.

Here at bene : studio, we have a great emphasis on leaving all of our projects in an understandable format not only for maintenance but to show future developer candidates the ideology and basis of well-formatted code. For this, we discussed the most important aspects of this and made a set of “rules” about what we consider as a well-formatted code.

Since the nature of our projects mostly revolves around the stack of Node.js, we are using a fantastic open-source tool, ESLint. This is a static code analyzer to quickly find any syntax or formatting errors. The greatest thing is not only finding those errors, but ESLint can fix many problems. Fixes are syntax-aware, which means it is not going to cause issues like any other find-and-replace algorithms.

Rules with ESLint

The way ESLint works is with a set of defined rules. Rules are either built-in or custom made. When using one you can select what error level the tool will show you upon encountering the given syntax. Let’s see an example configuration:

{
“rules”: {
“semi”: [“error”, “always”],
“quotes”: [“error”, “double”]
}
}

Each value inside the rules object is a rule specification. For example, semi means the usage of semicolons at the end of each line. Rule definition can be done in a form of a JavaScript array. First value of this array is the error level and can be one of the following values:

0 or “off”: rule is turned off
1 or “warn”: will give you a warning
2 or “error”: will give you an error (exit code is 1 of the process)

The second array value is an additional parameter to the rule itself. Meaning that semicolon check will run for all line endings. But quote checking will only throw error when the quote character is not a double one.

As you can see the list of available rules is quite huge and on top of that each rule can be customized.

If somebody wouldn’t like to bother setting up rules that can be done with a simple extension. The configuration file itself can extend existing configurations, e.g. the recommendation of ESLint:

{
“extends”: “eslint:recommended”
}

This will turn on all the recommended rules.

Inspiration

Our main goal was to build an easily configurable linter package that we can use in every project. Basically we usually use our boilerplate on every project for consistency. But every team has a different need for the linter. We want to assure you with our own linter package. When we started looking for some solution we soon met the yoctol’s solution which provides the first step forward the goal.

Our solution

The main building blocks for our solutions are ESLint pre-defined configurations. Two of the main important configurations are Airbnb and the Yoctol. Apart from these, plugins are also used, these are a set of additional rules. A great example is eslint-plugin-import-order-alphabetical. It makes sure that all top-level imports in a JS file are sorted in a nice and readable order.

The structure along which we divided the rules with no claim of being exhaustive:

Accessibility: jsx-a11y redefinitions
Best-practices: rules what we love
Imports: we like well organized imports
Node: prevent “require()” usage
Prettier: basic pretty stuff
React: it makes airbnb more strict
Spacing: one of the most important part (because programmers are lazy as sh!t)
Tests: some Jest specific validations