Writing Readable Code: Style and Conventions
Variable names must start with a letter or underscore, contain only letters, digits, and underscores, and can be any length.
A Name Is a Contract
When you create a variable, you give a value a name that will appear throughout your code. That name acts as a contract: it tells readers, including your future self, what the value represents. Python first applies hard rules to decide whether the name is legal. After a name passes those rules, naming conventions help make it readable and consistent.
The Character Rules
A Python variable name must start with a letter or an underscore. After the first character, it may contain letters, digits, and underscores. A name can be any length. These rules describe what Python permits; they do not by themselves guarantee that the name will be easy for a person to understand.
| Pattern | Result | Reason |
|---|---|---|
| Starts with a letter | Legal | A letter is allowed as the first character |
| Starts with an underscore | Legal | An underscore is allowed as the first character |
| Contains letters, digits, and underscores | Legal | These are the permitted character types |
| Starts with a digit | Illegal | A variable name cannot begin with a digit |
| Contains a space | Illegal | Spaces are not allowed |
| Contains a hyphen | Illegal | Hyphens are not allowed |
| Contains another special character | Illegal | Special characters are not allowed |
The first character has a stricter rule than the characters that follow.
Testing Candidate Names
Checking Three Candidate Names
Decide whether each candidate follows Python's variable-name rules: total_items, 2nd_place, and item-count.
total_items: This name starts with a letter and contains only letters and an underscore, so it follows the character rules.
2nd_place: This name contains permitted characters, but it starts with a digit. That makes it illegal.
item-count: This name starts correctly, but it contains a hyphen. Hyphens are not allowed.
total_items is legal. 2nd_place and item-count are illegal.
From Vague to Self-Documenting
Python convention uses snake_case for regular variables. Snake_case uses lowercase words separated by underscores. This convention improves readability and consistency. A descriptive name gives readers information about what the value represents, while a vague name such as x gives them much less information.
Consider a value that represents a number of items. The name x is legal, but it does not tell a reader what the value represents. The generated name total_items is also legal and communicates more information while following snake_case.
Using Underscores Well
Underscores have two important roles in this topic. Inside a regular variable name, underscores separate lowercase words in snake_case, as in total_items. At the beginning of a name, an underscore is valid according to Python's naming rules, but leading underscores are reserved for library code. Avoid leading underscores in regular applications.
Starting a variable name with a digit
Python variable names cannot start with a digit.
Fix:
Begin the name with a letter or underscore, then use permitted characters.Using spaces in a name
Spaces are not allowed in variable names.
Fix:
Use snake_case, such as total_items.Using a hyphen as a word separator
Hyphens are not allowed in variable names.
Fix:
Use an underscore between words, such as item_count.Using a vague name when a descriptive name is available
The name is legal but gives readers little information about what the value represents.
Fix:
Choose a descriptive snake_case name, such as total_items, when that meaning is known.Using a leading underscore for a regular application variable
Leading underscores are reserved for library code.
Fix:
Avoid a leading underscore in regular applications.
Practice the Naming Check
For each candidate, decide whether it is legal. If it is legal, decide whether it follows the regular-variable naming convention and communicates meaning clearly: user_name, 3rd_option, account balance, item_count, and _internal_value.
Hints
- Check the first character before checking the rest of the name.
- Look for spaces, hyphens, or other special characters.
- For a regular variable, look for lowercase words separated with underscores.
- Remember the rule about leading underscores in regular applications.
- Use a two-stage review. First, check legality: the name must start with a letter or underscore, contain only letters, digits, and underscores, and may be any length. Second, check readability: use descriptive lowercase snake_case names for regular variables, use underscores to separate words, and avoid leading underscores in regular applications.
Key Takeaways
- A Python variable name must start with a letter or underscore.
- After the first character, a name may contain letters, digits, and underscores, and it may be any length.
- Digits, spaces, hyphens, and special characters become problems when they violate these character rules.
- Use descriptive lowercase snake_case names for regular variables to improve readability and consistency.
- Underscores are useful between words, but leading underscores should be avoided in regular applications because they are reserved for library code.