TS · maintainability

←Previous Next→

no-type-member-comment-wall

Flag an object type whose member comments mostly re-spell the members' own names and types.

commentWall Rule source Tests Catalog JSON

Why

Repetitive member comments add scanning cost while hiding the comments that describe facts absent from the type.

Fix

Delete comments that restate member names or types and keep comments that add constraints or behavior.

Examples

Before — flagged Do not restate member names and types

src/credentials.ts

interface Credentials {
  // Database host.
  host?: string;
  // Database host port.
  port?: number;
  // Database username.
  username?: string;
  // Database password.
  password?: string;
}

After — preferred Let clear member names and types stand alone

src/credentials.ts

interface Credentials {
  host: string;
  port: number;
  username: string;
}

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