Skip to content
Sarj Sarj Sarj Standards

excessive-commentary

Flag long standalone implementation commentary that should be expressed by code.

excessive Rule source Tests Catalog JSON

Why

Narrative implementation paragraphs compete with the code and can drift independently from behavior.

Fix

Delete narration and clarify names, types, or structure; retain only durable constraints and external contracts.

Examples

Before — flagged Adapter paragraph narrates application behavior
src/adapter.ts
/**
 * This file is the seam between the draft and backend models.
 * Everything above it uses the local application representation.
 * Everything below it uses a separately mirrored wire representation.
 * Field names use the API shape while the draft uses another shape.
 * This module translates every field between those representations.
 * The backend models changed several times during early development.
 * Each historical change required another edit in this adapter file.
 * The write half previously assembled several resources in one payload.
 * It now saves those resources separately through their own routes.
 * Clear contract types and generated clients should express this boundary.
 */
import type { Draft } from "./draft";
After — preferred Concrete wire compatibility constraint remains local
src/adapter.ts
// Legacy clients send `execution_phase` until API-812 is retired.
// Keep conversion in GeneratedClientAdapter.
export const phase = raw.execution_phase;