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
Before — flagged A scalar payload marker cannot waive a narrated comment wall
config.yaml
payload: |
  # sarj-noqa: SARJ300
# Set build name
name: build
# Run build command
run: make build
# Set deploy image
image: app
# Run deploy command
command: deploy
After — preferred A real exact-code comment retains its local wall waiver
config.yaml
# sarj-noqa: SARJ300
# Set build name
name: build
# Run build command
run: make build
# Set deploy image
image: app
# Run deploy command
command: deploy

Files

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