eslint-plugin-write-good-comments-2

June 19, 2026 · View on GitHub

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

npm license. npm total downloads. latest GitHub release. GitHub stars. GitHub forks. GitHub open issues. codecov.

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

RuleFixPreset 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