Skip to content
Sarj Code Standards

no-comment-cruft

Commented-out code, mechanical narration, decorative banner, or untracked work marker.

SARJ016 Rule source Tests Catalog JSON

Why

Mechanical narration and dead code obscure the constraints and rationale that comments should preserve.

Fix

Delete the cruft. If author-controlled code is unclear without narration, clarify names, types, or structure; keep only concise comments for a hidden reason or constraint.

Examples

Before — flagged Dead code preserved as a comment
service.py
value = load()
# return value
save(value)
After — preferred Comment records an external constraint
service.py
value = load()
# Keep this ordering because Clerk caches the first lookup.
save(value)
Before — flagged An editorial prefix does not add meaning to a section label
service.py
# NOTE: Type aliases
type UserId = str
After — preferred An editorial prefix may still carry a real constraint
service.py
# NOTE: Keep this order because the registry caches it.
register()
Autofix output
service.py
type UserId = str