Skip to content
Sarj Code Standards

excessive-commentary

Delete comment paragraphs that exactly repeat the following ordered action names.

SARJ434 Rule source Tests Catalog JSON

Why

A paragraph that repeats the same action names in the same order adds a second copy of the implementation. Comment length alone cannot distinguish noise from a necessary technical constraint.

Fix

Delete the duplicate narration and keep the authored action names. Preserve constraints, references, uncertainty, ordering requirements and side-effect explanations that add meaning beyond those names.

Examples

Before — flagged A paragraph exactly repeats two flat action names
app.py
def activate():
    # Load current account profile activation settings
    # Build current account profile activation response
    load_current_account_profile_activation_settings()
    return build_current_account_profile_activation_response()
After — preferred The original activation paragraph explains why all failures are returned
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