Skip to content
Sarj Sarj Sarj Standards

config-comment-wall

four or more nearby configuration comments mostly repeat their entries

SARJ300 Rule source Tests Catalog JSON

Why

Repeated comments that merely narrate adjacent configuration hide constraints and make the file harder to scan.

Fix

Delete narration. Where names are author-controlled, clarify jobs, steps, targets, keys, or sections; keep comments only for constraints or rationale.

Examples

Before — flagged Repeated comments restate adjacent entries
workflow.yml
# Set build name
name: build
# Run build command
run: make build
# Set deploy image
image: app
# Run deploy command
command: deploy
After — preferred Rationales keep a mixed comment cluster useful
workflow.yml
# Keep one worker because uploads race.
concurrency: 1
# Retain three retries because the upstream API is eventually consistent.
retries: 3
# Set build name
name: build
# Set build image
image: app

Files

**/*.{yaml,yml,toml,jsonc}