Skip to main content

write-good-comments

Targeted pattern scope​

This rule checks regular line comments, block comments, and JSDoc-style comment text with write-good.

It automatically skips common directive comments such as ESLint disables, TypeScript @ts- directives, and similar tool-control comments that should not be linted as prose.

What this rule reports​

The rule reports prose that write-good considers weak, vague, repetitive, or needlessly wordy. That includes phrases like In order to, some adverbs, clichés, passive voice, and optional e-prime violations.

Why this rule exists​

Comments are documentation. When they become vague or bloated, they make code harder to maintain. This rule gives teams a lightweight, automated nudge toward clearer comment writing without trying to be a full grammar checker.

❌ Incorrect​

// In order to handle this edge case, we basically just try again.
retry();
/*
 * It is important to note that this function is very unique.
 */
runTask();

✅ Correct​

// Retry once for this edge case.
retry();
/**
 * Run the task once after validation succeeds.
 */
runTask();

Behavior and migration notes​

  • The rule is report only. It does not autofix comment prose.
  • It preserves precise source locations by linting normalized comment text while keeping offsets aligned with the original comment source.
  • JSDoc decoration (*) is ignored for analysis, so the rule lints the prose instead of the formatting characters.
  • Directive comments such as // eslint-disable-next-line ... are ignored.

Additional examples​

Enable upstream checks selectively:

export default [
    {
        plugins: {
            "write-good-comments": writeGoodComments,
        },
        rules: {
            "write-good-comments/write-good-comments": [
                "error",
                {
                    eprime: true,
                    whitelist: ["read-only"],
                },
            ],
        },
    },
];

ESLint flat config example​

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

export default [
    {
        files: ["**/*.{ts,tsx,js,jsx}"],
        plugins: {
            "write-good-comments": writeGoodComments,
        },
        rules: {
            "write-good-comments/write-good-comments": "error",
        },
    },
];

When not to use it​

Do not use this rule when a project intentionally keeps comments terse or when the team prefers a looser, editor-only prose linting workflow.

If the defaults are too noisy, keep the rule and disable individual upstream checks before turning the rule off entirely.

Package documentation​

Upstream package documentation:

Supported options mirror the upstream package:

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

Rule catalog ID: R001

Further reading​