Naming Rules, and Names Worth Reading

Part I · Module 2 · Chapter 2.4 · Naming Rules, and Names Worth Reading

1. What Python Accepts

A name may contain letters, digits and underscores. It may not start with a digit. That is essentially the whole rule.

error_count = 0
seed_1 = 4210
_internal = "scratch"
runDir = "runs/smoke"

All four are legal. The last one is legal but not conventional — §5 comes back to it.

2. What Python Rejects

Three ways to get it wrong, each with a distinct message.

Starting with a digit

2nd_run = "retry"

SyntaxError: invalid decimal literal

Python began reading 2 and expected a number, then found letters. Rename it run_2 or second_run.

A hyphen

test-name = "axi_smoke"

SyntaxError: cannot assign to expression here. Maybe you meant '==' instead of '='?

The message is confusing until you know why: Python read test - name as a subtraction, and you cannot assign to a subtraction. Use an underscore: test_name.

A space

test name = "axi_smoke"

SyntaxError: invalid syntax

Two words where Python expected one. Again, use an underscore.

3. Capitalisation Counts

Python is case-sensitive, so these are three different names:

seed = 1
Seed = 2
SEED = 3
print(seed, Seed, SEED)

1 2 3

That is not a feature to use. It is a hazard to avoid — a file containing both seed and Seed is a bug waiting to be filed. Pick one spelling per concept.

This is also the most common cause of a NameError that looks impossible: the name is assigned, just not with the capitalisation you used when reading it back.

4. Words Python Has Reserved

Some words are part of the language itself and cannot be used as names.

class = "axi_smoke"

SyntaxError: invalid syntax

You have already met several reserved words without needing them as names: True, False, None. Others — if, for, def, import, return, while, class — belong to features taught in later modules.

You do not need the list. If you accidentally use one, Python tells you immediately with a SyntaxError, and renaming fixes it. If you are curious, help("keywords") at the interactive prompt from Chapter 1.5 prints them all.

5. Conventions Worth Following

Chapter 2.2 introduced snake_case — lowercase words joined by underscores. Three further conventions complete the picture:

• runDir is legal but not Python. That style is normal in other languages and looks out of place here. Use run_dir.
• A leading underscore means "internal". _scratch signals this is not for you to use from outside. Nothing enforces it; it is a message to a reader. You will not need it in Part I.
• ALL_CAPITALS means "treat as fixed". Also unenforced, also a message. Chapter 2.14 is entirely about that one.

6. Names Worth Reading

Python accepts x. A colleague inheriting your script does not.

Say what it holds. error_count tells a reader what the value means. n does not, and int_value tells them the type — which they could already see — rather than the meaning.

Be specific enough to distinguish. In a file dealing with two paths, path is not a name; log_path and report_path are.

Do not encode the type. str_name and name_string add noise. Chapter 2.10 gives you a way to ask Python about a type when you need to; the name does not have to carry it.

Stop before it becomes a sentence. the_number_of_errors_found_in_this_run is worse than error_count, not better.

Be consistent. If it is run_dir on line 4, it is run_dir on line 40 — not rundir, not runDirectory.

7. Predict, Run, Observe

For each, predict whether Python accepts it, and if not, which error appears:

test_name = "smoke"
test2 = "burst"
2test = "rw"
_temp = 0
max-retries = 3
maxRetries = 3
None = 5

Run them one at a time — several will stop the file, and from Chapter 1.4 you know that a SyntaxError means nothing runs at all.

(Accepted: test_name, test2, _temp, maxRetries — the last legal but not conventional. Rejected: 2test starts with a digit, max-retries contains a hyphen, None = 5 assigns to a reserved word.)

8. Exercise

Exercise 1 — fix the illegal names. Each line fails. Rename each so it works, keeping the meaning:

1st_seed = 4210
error count = 0
run-dir = "runs/smoke"
class = "burst"

Exercise 2 — improve the legal ones. These all run. Rewrite them with better names; you will have to infer the meaning, which is the exercise:

a = "axi_smoke"
tmp = 4210
flag = True
s = "runs/axi_smoke_4210"

Exercise 3 — the shadowing trap. Predict what happens, then run it:

print("before")
print = "oops"
print("after")

Which line fails, and why does the first line still work? Explain using the model from Chapter 2.3.

Exercise 4 — the invisible bug. This runs and prints something surprising. Predict the output, then run it, then say what a reviewer should have caught:

error_count = 0
Error_count = 5
print(error_count)

9. Summary

• Letters, digits and underscores; not starting with a digit. That is the whole legality rule.
• No hyphens, no spaces. A hyphen is read as subtraction, which produces a confusing message.
• Names are case-sensitive. seed and Seed are different names, and having both in one file is a bug waiting to happen.
• Reserved words are protected and produce an immediate SyntaxError. You do not need to memorise the list.
• Built-in names are not protected. print = 5 is legal and breaks print for the rest of the file, silently.
• snake_case is the convention; _leading means internal, ALL_CAPS means treat as fixed.
• A good name says what the value means, is specific enough to distinguish, does not encode the type, and stays short enough to read.

Naming is settled. The next chapter covers a piece of assignment syntax that becomes useful once you have several related values to set up at once.