Constants by Convention

Part I · Module 2 · Chapter 2.14 · Constants by Convention

1. Python Has No Constants

MAX_RETRIES = 3
print(MAX_RETRIES)

MAX_RETRIES = 99
print(MAX_RETRIES)

3
99

Both assignments worked. No error, no warning, nothing. MAX_RETRIES is an ordinary name and behaves exactly as retries would.

If you have written C or SystemVerilog, this is a genuine difference. There is no const, no parameter, no localparam, and no compiler that will refuse. Python has no mechanism for preventing reassignment.

2. What the Capitals Actually Do

The convention is that a name written in capitals, with underscores between words, marks a value that is not intended to change:

MAX_RETRIES = 3
DEFAULT_TIMEOUT = 3600
LOG_NAME = "sim.log"

Python treats these exactly as it treats max_retries. The capitals are addressed entirely to human readers, and what they say is:

This value is set once, near the top, and the rest of the file assumes it does not move. If you are about to reassign it, you are probably doing something the author did not intend.

This is the same category as snake_case from Chapter 2.4 and the leading underscore for internal names. Python's style relies heavily on agreements between engineers rather than enforcement.

3. Why Bother

Because of what the alternative looks like.

print("Retrying, attempt 2 of 3")
print("Waiting up to 3600 seconds")
print("Giving up after 3 attempts")

Three numbers, no explanation. A reader has to work out that 3 means a retry limit and 3600 is a timeout in seconds. Worse, when the retry limit becomes 5, somebody must find every 3 in the file and decide, one at a time, which ones mean retries and which mean something else entirely.

Numbers like this appearing directly in code are usually called magic numbers, and they are the thing the convention exists to prevent:

MAX_RETRIES = 3
DEFAULT_TIMEOUT = 3600

print("Retrying, attempt 2 of 3")
print("Waiting up to 3600 seconds")
print("Giving up after 3 attempts")

Two improvements at once. The value now has a name saying what it means, and there is one place to change it.

4. What Goes in Capitals

Values that are fixed for the run and set in one place:

• limits and thresholds — MAX_RETRIES, MIN_COVERAGE
• defaults — DEFAULT_TIMEOUT, DEFAULT_SEED
• fixed names and locations — LOG_NAME, REPORT_DIR

What does not go in capitals: anything that legitimately changes as the script runs. A counter is not a constant, however tempting the shouting looks.

MAX_RETRIES = 3        # fixed for the run — capitals
attempt_count = 0      # changes as the script runs — ordinary name

5. It Is Only a Promise

Worth being blunt about, because the capitals can create false confidence.

MAX_RETRIES = 3
MAX_RETRIES = 99       # legal. Python does not care.
print(MAX_RETRIES)

99

Nothing protected it. If a script reassigns a capitalised name, that is a bug a reviewer has to catch, because nothing else will.

6. Where These Live

By convention, near the top of the file, after any comments and before the work begins:

# Retry policy for a flaky tool.
MAX_RETRIES = 3
DEFAULT_TIMEOUT = 3600

print("Starting run")
print("Retry limit:", MAX_RETRIES)

Starting run
Retry limit: 3

Putting them together at the top means somebody adjusting the script's behaviour has one place to look — which is the entire benefit.

7. Predict, Run, Observe

MAX_RETRIES = 3
print(MAX_RETRIES)

MAX_RETRIES = 5
print(MAX_RETRIES)

attempt = 1
print(attempt)

3
5
1

Nothing failed. If you expected an error on the reassignment, that expectation came from another language — and noticing that is the point of the exercise.

8. Exercise

Exercise 1 — remove the magic. Rewrite this so the two values are named constants at the top:

print("Timeout is 3600 seconds")
print("Maximum 3 retries")

Exercise 2 — capitals or not. For each, say whether it should be a capitalised constant or an ordinary name: (a) the maximum number of retries; (b) how many retries have happened so far; (c) the default log file name; (d) the name of the test currently running; (e) the coverage percentage required to sign off.

Exercise 3 — the false guarantee. A colleague says "I made it a constant so it can't change". Correct them in one sentence, and name the one thing that actually would catch an accidental reassignment.

Exercise 4 — judge the file. A script has TIMEOUT = 3600 at the top and, forty lines later, TIMEOUT = 60 inside its main body. It runs without error. Describe what a reader of line 5 now believes that is not true.

9. Summary

• Python has no constants. No keyword, no declaration, nothing that prevents reassignment.
• ALL_CAPITALS is a convention meaning this value is not intended to change. It is addressed to readers, not to the interpreter.
• The convention prevents magic numbers — unexplained values scattered through a file with no single place to change them.
• Capitals are for values fixed for the run: limits, defaults, fixed names. Not for counters.
• Put them at the top, so there is one place to look.
• It is a promise, not a guarantee. If a value genuinely must not change, code review and tests are the protection.

That completes Module 2 — Variables and Data Types. You can now hold a value under a name, you know what = actually does and what it does not, you have met every basic value type Python provides, and you can find out what you are holding and convert it when it is the wrong thing.

What you cannot yet do is compute with any of it. Every example so far has stored a value and displayed it; nothing has added two numbers, compared two values, or combined two conditions. Module 3 — Operators and Expressions is where the values start doing work.