TS · maintainability

←Previous Next→

no-declaration-comment-wall

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

commentWall Rule source Tests Catalog JSON

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.

Examples

Before — flagged Do not restate every enum member

src/status.ts

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

After — preferred Let clear member names stand alone

src/status.ts

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

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"
}