Skip to content
Sarj Sarj Sarj Standards

no-long-comment

Flag unusually large unstructured JSDoc blocks in implementation code.

tooLong Rule source Tests Catalog JSON

Why

Large narrative comments become stale and obscure the local facts that belong beside the code.

Fix

Keep only durable local constraints and express the remaining behavior in code.

Examples

Before — flagged One paragraph narrates a chart's design history
src/chart.ts
/**
 * The ports chart shows arrivals and departures across the network.
 * It was originally a line chart, but the lines crossed too often.
 * Bars make adjacent ports easier to compare at a glance.
 * The axis starts at zero so visual differences stay proportional.
 * A single series uses the site navy for brand consistency.
 * Empty ports use a neutral ink so missing traffic remains visible.
 * Tooltip values repeat the units shown on the vertical axis.
 * The chart intentionally keeps labels horizontal on wide screens.
 */
export function PortBars() {
  return null;
}
After — preferred Paragraphs separate a component's durable constraints
src/composer.ts
/**
 * Shared composer.
 *
 * It serves the room. It serves task comments. It stays visually calm. It accepts attachments.
 *
 * The `tone` prop supplies task styling. The `leadingTools` prop supplies controls.
 * The parent owns uploads. The component owns focus.
 */


export const Composer = forwardRef(function Composer() {
  return null;
});