Is well-formatted code important today?

well formatted code header

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.

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

Contribution

You can find the source code on our Github

We invite everyone to leave feedback in the form of an issue or contribute by creating a pull request.

Did you like this?

Want to ask some questions? Share them with us via e-mail to partner@benestudio.co and we can set up a talk with our engineers.

Fancy working for the studio where you can work on international projects and write articles like this? Check out our open positions!

Looking for a partner for your next project? Check out our services page to see what we do and let’s set up a free consultation.

well formatted code header

Let bene : studio enhance
your digital product!