Proposal for the addition of formatting and linting

[4141done]

Proposal

Add formatting via prettier and basic linting with eslint. Pull requests would be required to be formatted and pass lint before being merged.

This will introduce a NodeJS development dependency to the project.

Why?

In general, both of these changes are aimed at keeping the codebase understandable, and focusing code review on logic and feature implementation rather than code-level nitpicks.

Formatting

In a codebase with many different contributors, it helps if basic formatting of code is very consistent. That way, all the code will appear to be formatted in the same style for those trying to read and understand the code. Additionally, new contributors will not need to worry about matching the formatting of the existing code if it is not their personal style.

In general, formatters produce code that is not as attractive as a carefully hand-formatted codebase. However, in a group situation it winds up being "good enough" and provide valuable consistency. Most formatters, including prettier, are intentionally not very configurable. We'll end up with a consistent style with few choices to argue over.

Linting

Linting plays a similar role but focuses on enforcing certain code patterns and preferences. Things like semicolon usage, disallowing the presence of undeclared variables, and more.

We would likely start with the EsLint recommended config with changes applied to encourage patterns that are more beneficial to njs' specific best practices.

Linting again focuses our conversation in pull requests to the logic and features at hand. It also ensures a consistent style for others as they start contributing.

How

We propose to add two new checks on pull requests for linting and formatting specifically. Submitters will be required to perform these checks themselves by running a command locally before committing.

Since the linting and formatting tools are written in NodeJS, NodeJS will need to be installed to perform these actions. To decrease barriers to doing this, we will provide an option to perform these actions in a docker container. Docker is already a required technology for this project. Likely these will commands will be abstracted into a Makefile. So you can run make format or make lint. npm based scripts will also be available for those who have nodejs installed locally and are used to those commands (ie npx prettier -w . or npm run format)

Comments and feedback are welcome.

[ivanitskiy]

as i was asked to take a look in person: here is the progress dekobon#1

[ivanitskiy]

it doesn't have GH actions, but rather only eslint and prettier, and many jsdocs fixes. it all required to make my VSC discover all that.