TypeScript · maintainability

no-declaration-comment-wall

eslint:no-declaration-comment-wall

Flag an enum body or class body whose member comments mostly re-spell the members' own names.

Default: error
Fix: none
Languages: typescript

Why

A dense block of repetitive member comments obscures the few comments that add information and drifts with renamed members.

Fix

Delete comments that restate member names and retain comments that explain constraints, lifecycle, or behavior.

Before / after

Executed by this rule’s unit tests.

Before

Do not restate every enum member

src/status.ts · focus

enum Status {
  /** The pending status. */
  Pending = 'pending',
  /** The finished status. */
  Finished = 'finished',
  /** The failed status. */
  Failed = 'failed',
}

After

Let clear member names stand alone

src/status.ts · focus

enum Status { Pending = 'pending', Done = 'done', Failed = 'failed' }

Limits

Only enum and class bodies meeting the configured comment-count and restatement-ratio thresholds are reported.

Message IDs

commentWall

Options

{
  "additionalProperties": false,
  "properties": {
    "maxNovelWords": {
      "description": "Most content words a comment may add beyond its member's own source and still count as a restatement.",
      "minimum": 0,
      "type": "integer"
    },
    "minCommentedMembers": {
      "description": "Fewest commented members that can count as a wall.",
      "minimum": 2,
      "type": "integer"
    },
    "minCommentedRatio": {
      "description": "Least share of the members that must be commented; below it the comments are group labels.",
      "maximum": 1,
      "minimum": 0,
      "type": "number"
    },
    "minRestatedRatio": {
      "description": "Least share of the member comments that must be restatements.",
      "maximum": 1,
      "minimum": 0,
      "type": "number"
    }
  },
  "type": "object"
}