Skip to content
Sarj Sarj Sarj Standards

excessive-commentary

Long standalone implementation commentary — make the code self-documenting and retain only durable constraints.

SARJ434 Rule source Tests Catalog JSON

Why

A paragraph that narrates nearby implementation behavior competes with the code and can drift independently from it.

Fix

Delete the narration and clarify names, types, or structure. Keep concise comments that record a durable constraint or externally owned contract.

Examples

Before — flagged Implementation paragraph narrates a validation helper
app.py
def activation_reasons():
    # Everything standing between this integration and being usable.
    # Returns all the reasons rather than the first failure.
    # Someone activating a half-built integration wants the complete list.
    # That avoids discovering one problem per round trip.
    reasons = []
    reasons.extend(integration_reasons())
    reasons.extend(endpoint_reasons())
    return reasons
After — preferred A concrete compatibility constraint remains local
app.py
# Legacy clients send `execution_phase` until API-812 is retired.
# Keep the adapter at this boundary so internal models stay camelCase.
phase = payload["execution_phase"]