JS code quality starter pack: linters, conventions, best practices

Valeriy Stepanov — Mon, 17 May 2021 20:01:53 +0000

This article is about my view to convention building.

It includes some basic examples including linting tools setup.

That can be interesting for developers who like to follow coding best practices and who want to improve their own or team code quality.

As for me, I've explained and use those concepts many times. So, putting them into article will be handy.

First of all you can look at my linting guide with the linter pack setup here.

Also you can grab my article from git repo here.

What is it for

Conventions should respect team's/framework's abilities and limitations.
Conventions is always a compromise. You should learn how to do that before doing conventions.
Compromise is based on the trust, and that's based on the respect and responsibility.
Respect yourself and others results of the work and time which has been spent.
Prepare and make discussions well:
- reduce the number of participants
- make and read agendas
- convert feelings into real facts and stories
- speak in plain English, avoid using abbreviations
- draw trees with facts decomposition
- write a summary and apply the decisions

reduce the number of reviewers
- More than one can be the cause of duplicated work and time spending while one of them/you out of work or busy
- If more than one participants is necessary, you should divide the code for each reviewer
check all code at once, reduce review-fix(ping-pong) time spending
actions:
- switch into PR branch
- execute and test at least one main functionality of the PR, prevent moving PR to QA engineers with silly issues like "forgot to run git add"
check the:
- unit test code coverage
- code convention compliance
- code complexity

Less code means less:
- bugs
- merge conflicts
- reading time
Do not shorten unit's names or line breaks:
- Long names and line breaks reduce analysis time and bugs count.
- Minifier will remove them anyway.
describe PR's scope in a task to help make the review and a test better:
- modules/components or domain areas which have been modified
- new functionalities were added and where
reduce the PR's scope, make a new subtask/story for:
- broken/disabled(xit/xdescribe) unit test
- optional parts of functionality/refactoring
- investigation and description(making notes/readmes) of how old code is working
execute before the pushing into repo:
- reformat and autofix all code using prettier, eslint and stylelint rules
- git pull && git merge origin master
- npm run lint
- npm run build
- npm run test

make functions private as much as possible
use camelCase
remove an unused code
reduce the code complexity:
- nested braces depth
- else blocks
- lines length
- lines per function
- params count
make names readable like:
- isSomethingEnabled
- onEventHappens
- getSomeValue
- setSomeValue
- parseValues
put notes to share your knowledge
- The code describes how things works, and your notes describes why or what for
- One short note can prevent hours of investigation or days of rewriting code back and forth
- Put comments in one line, after the code not to increase lines number
- Put jsdoc in one line not to increase lines number. In popovers they are automatically reformatted.
- Put long notes in readme files: usage examples
make separate unit test assertion for:
- every input option
- every output value
- every possible state: init, loading, disabled, broken(reproduce exact issue), valid
add in every unit test not only the final state, but state transition: before/after loading, before/after issue fixing