Skip to content
Sarj Standards

Python · maintainability

prefer-self-documenting-constant

python:prefer-self-documenting-constant

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

Code
SARJ097
Default
error
Fix
none
Languages
python

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.

Before / after

Executed by this rule’s unit tests.

Before

Comment is the only source of the unit

app/settings.py · focus
# Request deadline in seconds.
REQUEST_DEADLINE = 10

After

Constant name carries its unit

app/settings.py · focus
# Request deadline in seconds.
REQUEST_DEADLINE_SECONDS = 10

Limits

  • Only direct module and class constants with attached comments and proven numeric or HTTP-status shapes are analyzed.
  • Generated code, directives, ambiguous comments, policy sentinels, and values already carrying the fact are excluded.