Consistency is one of the most important factors in a codebase. It gives new developers an orientation and direction how to write new code. It keeps the code understandable, clear and free from bikeshedding, so developers can focus on real problems instead of indulging in discussions on their preferred codestyle and individual taste.
The same is true for linters. They help you to comply with common best practices and to avoid potential problems. Linters and code formatters are essential tools for state-of-the-art software engineering.
Setup ESLint and Prettier
Next we have to configure ESlint so that it works together with
Prettier. Some ESlint rules are not compatible with the Prettier
formatting by default. ESlint is configured via two files
.eslintignore. Both files need to be created in
your project root.
The Prettier configuration file is
Here we define a maximum line length of 80. I am also an advocate of trailing commas. This setting keeps the git diffs clean and as small as possible. You can find more in-depth information about Prettier configuration here.
With all this in place you can lint and format your code base:
In the above code block, we had to use the path to the local node_modules/ folder, otherwise the ESlint and prettier binaries would not be found. I recommend to install Prettier and ESlint as global npm modules, then you can use them directly. This enables editors to leverage prettier and ESlint too. You are then able to incorporate both tools in your usual workflow. For example, i configured my editor to show ESlint errors during typing and formatting is done automatically when I save the current file.
It’s good practice to enforce these rules in order to preserve
consistency with a git pre-commit hook. Just install
lint-staged for this
purpose. They facilitate the configuration of git hooks, so you do not
have to write the corresponding
pre-commmit hook manually.
After the installation you need configure husky and lint-staged
modules in your local project’s
package.json. In this example, I run
eslint --fix and
prettier --write during a pre-commit for all
changed files. This makes sure that no inconsistent code will ever be
committed to your codebase.
You can find a fully configured project template on my github.
One more word about consistency
I can only emphasize once more that consistency is one of the most important characteristics of a good codebase. Especially if your project has multiple contributors but even if you work alone. Consistency keeps the code maintainable and helps to keep up high quality.
When I start working in a new team on a existing codebase, the first thing I do is checking the codebase regarding consistency. Is the formatting always the same? Is immutability preferred? Are threads or asynchronous programming with callbacks used? Or promises? Or async-await? Can I see re-emergent patterns? Are class, function and variable names consistent? Is Domain Driven Design used?
The main point is that consistency should be apparent across the whole codebase and that new team members are able to deduct how code should look like. The existing codebase acts like a model. For example if you are in doubt how to write a new controller with a repository, the following question should be answerable from the existent code: Do other controllers exist which act as a template? Do all controllers comply to the same patterns? Do they have the same annotations? Do they use the same dependency injection methods like constructors, setters, or field injection? Are all controllers tested the same way? Do controllers have the same tests like unit and component tests? If the model is inconsistent or askew, new team members are left in uncertainty. They never know if they comply to existing coding guidelines because the guidelines are not visible in the source code itself. Even if they are visible but exceptions exist, it is hard for an outsider to decide what is right. In bad projects, i encountered lengthy coding guidelines in Confluence but the real code diverged a long time ago from these written guidelines. The best guidelines and rules are often deducible from the existing code. Another thing you want to avoid due to lacking consistency is time consuming and exhausting discussions in pull requests. To avoid senseless work, be consistent all the time with your rules and guidelines and stick to them. Whenever you can enforce them or check them automatically, do it. It will save you a lot of time.
By now, you went through a lot of project setup effort and learned about the importance of consistency. But if you apply consistency with linters and automatic code formatters, you will have great tools which help you to write better code.
When you first time run a linter on your project, do not worry if you encounter hundreds of warnings. This is normal, just get rid of them step-by-step, e.g. reduce the number of lint-warnings with every pull request.
I hope, I could convince you that consistency matters. And that the winning trio with ESlint, Prettier and Typescript improves your codebase.