airbnb / airbnb/javascript

Non-Enforced Rules Should be Clearly Documented in the README.md

Open
#2,205 7 comments 3 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
148k
Forks
26.6k
PR merge metrics
No merged PRs in 30d

Description

1) The users of this style guide will probably expect that all of the rules that it prescribes will be enforced by eslint. However, this is not the case - there is a secret, non-documented segmentation where some rules are enforced and others are not, because they would be "too noisy on a legacy codebase". An example of a problematic rule like this is covered in issue #2020. I propose that all of these exceptions should be clearly documented in the README.md file and not hidden from the end-user. Specifically, I propose that the suffix of each rule in question is modified, e.g. something along the lines of `eslint: prefer-const, no-const-assign` --> `eslint: prefer-const (not enforced), no-const-assign (not enforced)`.

2) As a separate but related issue, some style prescriptions in particular are not lintable. For example, [the comparison shortcuts](https://github.com/airbnb/javascript#comparison--shortcuts) rule is not lintable, as mentioned in issue #1489. However, just like the previous point, this is opaque to the end user. Specifically, I propose that a suffix is **added** to each rule in question, e.g. something along the lines of `(not lintable)`. Adding these suffixes would further inform the end-user about what is being linted and what is not being linted in a much more explicit way.

While I don't have time to perform a PR myself, I wanted to open an issue so that at least these problems are more visible.

In closing, I want to thank the maintainers for this excellent style guide.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing the rule lists and descriptions in README.md, then compare the documented prescriptions with the enforcement exceptions described in issues #2020 and #1489. Done means every non-enforced and non-lintable rule is clearly marked for end users, with the README consistently distinguishing those categories.

Written by the indexing model from the issue text.

Assessment

Tech stack
eslint, javascript
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.