Master Python Variable Naming: Rules, Best Practices, and Common Pitfalls

In Python, variable names are identifiers you assign to stored data and use to reference that data in code. Good naming improves readability and maintainability.

1. Basic Naming Rules

Allowed characters

Letters (a‑z, A‑Z)

Digits (0‑9)

Underscore (_)

Disallowed characters and keywords

Spaces – e.g., my var ❌

Special symbols such as @, #, $, %, &, * or - – e.g., my@var ❌

Python reserved words – e.g., if = 10 ❌

2. Legal and Illegal Examples

✅ Legal variable names

age
name
student_name
user123
totalScore
is_active
MAX_VALUE

❌ Illegal variable names

1age          # cannot start with a digit
if            # keyword
student-name  # hyphen not allowed
my var        # contains space
@name         # special character
first.name    # dot not allowed

3. Recommended Style (Best Practices)

1. Use snake_case

Lowercase letters separated by underscores – the community‑recommended style for variables and functions.

Examples:

student_name
total_score
is_active
user_id
max_value

2. Avoid single‑letter names (except temporary loop variables)

Prefer descriptive names over a, b, x unless used in short loops.

3. Use meaningful names

Names should describe the stored data or purpose, e.g., name, age, is_student.

4. Avoid Chinese or pinyin

Even though Unicode is allowed, English words improve international collaboration.

4. Constant Naming (Convention)

Constants are typically written in all‑uppercase letters with underscores.

MAX_USERS = 100
PI = 3.14159
DEFAULT_TIMEOUT = 30

5. Common Examples

✅ Good variable naming

# Descriptive variable names
student_name = "Alice"
age = 25
is_student = True
total_score = 95
user_id = 12345

# Function example
def calculate_area(radius):
    pi = 3.14159
    area = pi * radius ** 2
    return area

# Loop variable
for i in range(5):
    print(i)

# List and dictionary
names = ["Alice", "Bob", "Charlie"]
user_info = {"name": "Alice", "age": 25, "is_student": True}

❌ Bad variable naming

# Non‑descriptive names
a = "Alice"
b = 25
c = True
d = 95

# Single‑letter loop variables without context
x = 10
y = 20
z = x + y

# Using keywords or special characters
if = 10  # keyword
my@var = "test"  # special character
1age = 25  # starts with digit
my var = "error"  # contains space

6. Summary of Key Points

Use only letters, digits, and underscores.

Do not start with a digit.

Python is case‑sensitive; Age, age, and AGE are distinct.

Avoid reserved keywords.

Prefer snake_case for variables and functions.

Choose descriptive, meaningful names.

Constants should be all caps with underscores.