eslint-plugin-write-good-comments-2

Lint source comments for prose quality, inclusive language, profanity, and task-comment hygiene.

eslint-plugin-write-good-comments-2 checks comment prose in JavaScript and TypeScript source files. It catches vague phrases, wordy constructions, passive voice, clichés, optional e-prime violations, potentially inconsiderate language, profane wording, misspellings, hard-to-read prose, and bare TODO-style task comments before unclear source documentation reaches review or production.

Installation

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

Quick start

import writeGoodComments from "eslint-plugin-write-good-comments-2";

export default [writeGoodComments.configs.recommended];

Presets

• recommended — best default for almost every project.
• all — explicit “everything we ship” preset.

You can also apply the rule manually inside your own scoped config object:

import writeGoodComments from "eslint-plugin-write-good-comments-2";

export default [
    {
        files: ["src/**/*.{ts,tsx,js,jsx}"],
        plugins: {
            "write-good-comments": writeGoodComments,
        },
        rules: {
            "write-good-comments/inclusive-language-comments": "error",
            "write-good-comments/task-comment-format": "error",
            "write-good-comments/write-good-comments": [
                "error",
                {
                    eprime: true,
                    whitelist: ["read-only"],
                },
            ],
        },
    },
];

Rules

• Fix legend:
  • 🔧 = autofixable
  • 💡 = suggestions available
  • — = report only
• Preset key legend:
  • 🟡 — writeGoodComments.configs.recommended
  • 🟣 — writeGoodComments.configs.all

Rule	Fix	Preset key
inclusive-language-comments	—	🟡 🟣
no-profane-comments	—	🟣
readability-comments	—	🟣
spellcheck-comments	—	🟣
task-comment-format	—	🟡 🟣
write-good-comments	—	🟡 🟣

Rule options

inclusive-language-comments

• allow: string[] — retext-equality rule ids to suppress for this rule.
• deny: string[] — retext-equality rule ids to report exclusively.
• noBinary: boolean — report binary pairings such as his or her.

no-profane-comments

• allow: string[] — retext-profanities rule ids to suppress for this rule.
• deny: string[] — retext-profanities rule ids to report exclusively.
• profanitySureness: 0 | 1 | 2 — minimum profanity confidence to report.

spellcheck-comments

• ignoreWords: string[] — repository-specific terms to accept.
• ignoreDigits: boolean — ignore words containing digits.
• ignoreLiteral: boolean — ignore quoted literals.
• maxSuggestions: number — maximum spelling candidates to include.
• normalizeApostrophes: boolean — normalize curly and straight apostrophes.

readability-comments

• age: number — target reader age for the readability model.
• minWords: number — minimum sentence length before analysis applies.
• threshold: number — maximum difficult-word ratio before reporting.

task-comment-format

• terms: string[] — task markers that should require a descriptive body.
• minDescriptionLength: number — minimum non-whitespace description length after optional task metadata.

write-good-comments

This rule mirrors the upstream write-good options:

• passive
• illusion
• so
• thereIs
• weasel
• adverb
• tooWordy
• cliches
• eprime
• whitelist: string[]

Ignored comment types

The comment-prose rules intentionally ignore tool-control comments such as:

• eslint-disable directives
• @ts-ignore, @ts-expect-error, and related TypeScript directives
• similar coverage or tool comments that are not normal prose

Documentation

• Overview
• Getting Started
• Rule docs
• Rule docs
• Rule docs
• Rule docs
• Preset docs
• Docusaurus site