Skip to content
Sarj Sarj Sarj Standards

prefer-self-documenting-constant

Encode a constant's units or HTTP status meaning in its name, type, or value.

SARJ097 Rule source Tests Catalog JSON

Why

A comment-only fact is lost at use sites and can drift independently from the constant it describes.

Fix

Add the unit to the name or type, use a unit-bearing value such as timedelta, or replace status integers with HTTPStatus members.

Examples

Before — flagged HTTP status collection uses bare integers
app/retry.py
# Retry HTTP responses 408 and 429.
RETRYABLE_HTTP_STATUS_CODES = {408, 429}
After — preferred HTTP status members carry protocol meaning
app/retry.py
from http import HTTPStatus


RETRYABLE_HTTP_STATUS_CODES = {
    HTTPStatus.REQUEST_TIMEOUT,
    HTTPStatus.TOO_MANY_REQUESTS,
}
Before — flagged Comment is the only source of the unit
app/settings.py
# Request deadline in seconds.
REQUEST_DEADLINE = 10
After — preferred Constant name carries its unit
app/settings.py
# The upstream gateway closes idle requests first.
REQUEST_DEADLINE_SECONDS = 10