eslint-plugin-write-good-comments

Installation ✴️ Usage ✴️ Examples

Enforce good writing style in your comments.

Using better writing style gives you more concise and expressive comments.

Installation

You'll first need to install ESLint:

npm i eslint --save-dev

Next, install eslint-plugin-write-good-comments:

npm install eslint-plugin-write-good-comments --save-dev

Shameless plug: I created this rule while working on my main pet-project, LibreLingo.

Usage

Add write-good-comments to the plugins section of your .eslintrc configuration file. You can omit the eslint-plugin- prefix:

{
    "plugins": [
        "write-good-comments"
    ]
}

Then configure the rules you want to use under the rules section.

{
    "rules": {
        "write-good-comments/write-good-comments": "warn"
    }
}

You can also disable or enable checks and whitelist words.

{
    "rules": {
        "write-good-comments/write-good-comments": [
            "warn", 
            {
                "passive": false,
                "whitelist": ["read-only"]
            }
        ]
    }
}

Examples

This plugin checks your writing using write-good. Check their documentation for a full list of what it checks for.

Passive voice

Checks for the usage of passive voice.

❌ Bad:

// files are handled by loadContent()

✔️ Good:

// loadContent() handles files

Illusion

Checks for cases when a word is repeated.

❌ Bad:

// loadContent() handles the files that the
// the plugin system doesn't support

✔️ Good:

// loadContent() handles the files that the
// plugin system doesn't support

Weasel words

Weasel words are words that are ambiguous or misleading.

❌ Bad:

// loadContent() handles the files that the
// plugin system probably doesn't support

✔️ Good:

// loadContent() handles the files that the
// plugin system doesn't support

Wordy expressions

Expressions or words that are too lengthy and complicated.

❌ Bad:

// by virtue of the fact that if there's no token, the user must be logged out

✔️ Good:

// because if there's no token, the user must be logged out