Naming rules and conventions in Python - Deep Dive

Overview - Naming rules and conventions

What is it?

Naming rules and conventions in Python are the guidelines and restrictions for creating names for variables, functions, classes, and other identifiers. Rules are the strict syntax requirements that must be followed for names to be valid. Conventions are recommended styles that make code easier to read and understand by humans. Together, they help programmers write clear and error-free code.

Why it matters

Without proper naming rules, code would not run because the computer wouldn't understand invalid names. Without conventions, code would be confusing and hard to maintain, especially when many people work on the same project. Good names act like labels on jars in a kitchen, helping everyone find and use ingredients quickly and correctly.

Where it fits

Before learning naming rules, you should know basic Python syntax and how to write simple programs. After mastering naming rules and conventions, you can learn about writing functions, classes, and modules where naming becomes very important for organization and clarity.

Mental Model

Core Idea

Naming rules are the must-follow syntax laws for identifiers, while naming conventions are the friendly style guides that make code readable and maintainable.

Think of it like...

Naming in programming is like labeling containers in a kitchen: rules are like the shape and size limits of the containers so they fit on shelves, and conventions are like writing clear labels so anyone can find the right spice or ingredient easily.

┌─────────────────────────────┐
│       Naming in Python       │
├─────────────┬───────────────┤
│   Rules     │  Conventions  │
├─────────────┼───────────────┤
│ - Start with letter/_        │
│ - Only letters, digits, _    │
│ - No spaces or symbols       │
│ - Not a keyword              │
│                             │
│ - snake_case for variables   │
│ - PascalCase for classes     │
│ - UPPERCASE for constants   │
│ - descriptive and clear     │
└─────────────┴───────────────┘

Build-Up - 7 Steps

1

Foundation

Basic identifier rules in Python

Concept: Learn the syntax rules that define valid names in Python.

In Python, names (called identifiers) must start with a letter (a-z, A-Z) or an underscore (_). After the first character, names can include letters, digits (0-9), or underscores. Names cannot contain spaces or special characters like @, #, or $. Also, names cannot be the same as Python reserved keywords like 'if', 'for', or 'class'.

Result

You can create names like 'age', '_count', 'total2', but not '2total' or 'my-name'.

Understanding these rules prevents syntax errors and ensures your code runs without name-related problems.

2

Foundation

Python reserved keywords

Concept: Recognize words that Python reserves for its own use and cannot be used as names.

Python has a list of reserved keywords such as 'def', 'return', 'if', 'else', 'while', 'class', and more. These words have special meaning in Python's language structure. Using them as variable or function names will cause errors. You can see the full list by running 'import keyword; print(keyword.kwlist)' in Python.

Result

Trying to name a variable 'for' or 'class' will cause a syntax error.

Knowing reserved keywords helps avoid naming conflicts that stop your program from running.

3

Intermediate

Common naming conventions for variables

🤔Before reading on: Do you think variable names should use uppercase letters or lowercase letters mostly? Commit to your answer.

Concept: Learn the recommended style for naming variables to improve code readability.

The common convention for variable names in Python is to use lowercase letters with words separated by underscores, called snake_case. For example, 'user_name', 'total_score', or 'is_active'. This style makes names easy to read and consistent across projects. Avoid using single letters except for counters or very short loops.

Result

Code with variables like 'user_name' is easier to understand than 'username' or 'UserName'.

Following conventions makes your code friendlier to other programmers and your future self.

4

Intermediate

Naming conventions for functions and constants

🤔Before reading on: Should constants be named like variables or differently? Commit to your answer.

Concept: Understand how to name functions and constants clearly and consistently.

Functions in Python follow the same snake_case style as variables, e.g., 'calculate_total' or 'send_email'. Constants, which are values that should not change, are named using all uppercase letters with underscores, like 'MAX_SIZE' or 'DEFAULT_TIMEOUT'. This difference helps readers quickly identify the purpose of each name.

Result

Seeing 'MAX_SIZE' in code signals a fixed value, while 'calculate_total' is a callable function.

Clear naming conventions communicate intent and prevent accidental changes to important values.

5

Intermediate

Class naming with PascalCase

Concept: Learn the style used for naming classes in Python.

Classes in Python are named using PascalCase (also called CapWords), where each word starts with a capital letter and no underscores are used. For example, 'UserProfile', 'BankAccount', or 'DataProcessor'. This style distinguishes classes from variables and functions at a glance.

Result

When you see 'UserProfile', you know it's a class, not a variable or function.

Using PascalCase for classes helps organize code and makes object-oriented programming clearer.

6

Advanced

Special naming patterns and their meanings

🤔Before reading on: Do you think names starting and ending with double underscores are normal variables? Commit to your answer.

Concept: Explore special naming patterns that have unique meanings in Python.

Names surrounded by double underscores, like '__init__' or '__str__', are special methods called 'dunder' methods. They have specific roles in Python's behavior, like initializing objects or converting them to strings. Names starting with a single underscore, like '_hidden', suggest that the item is for internal use only (a convention, not enforced). Names starting with double underscores, like '__private', trigger name mangling to avoid name clashes in subclasses.

Result

Recognizing these patterns helps you understand Python's object model and write better classes.

Knowing special naming conventions unlocks advanced Python features and prevents accidental misuse.

7

Expert

Balancing readability and brevity in naming

🤔Before reading on: Is it better to always use very long descriptive names or very short names? Commit to your answer.

Concept: Learn how expert programmers choose names that are clear but not overly long.

While descriptive names improve clarity, excessively long names can clutter code and reduce readability. Experts balance this by choosing concise yet meaningful names, using common abbreviations when appropriate, and relying on context. For example, 'num_items' is better than 'number_of_items_in_the_list'. Also, consistent naming across a project helps readers predict and understand names quickly.

Result

Code becomes easier to read and maintain without unnecessary verbosity.

Mastering naming balance is a subtle skill that greatly improves code quality and team collaboration.

Under the Hood

Python's interpreter uses naming rules to parse code and identify variables, functions, and classes correctly. It checks that names follow syntax rules to avoid errors. Naming conventions do not affect how code runs but guide humans reading the code. Special names like dunder methods are recognized by Python's internal mechanisms to provide built-in behaviors, such as object creation or string representation.

Why designed this way?

The strict rules prevent ambiguous or invalid names that would confuse the interpreter. Conventions evolved from community experience to make code more readable and maintainable, especially in large projects. Special naming patterns like dunder methods were introduced to allow Python to support powerful features without conflicting with user-defined names.

┌───────────────┐
│  Source Code  │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│  Lexer/Parser │  ← Checks naming rules (syntax)
└──────┬────────┘
       │
       ▼
┌───────────────┐
│  Symbol Table │  ← Stores names and their types
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Interpreter/  │  ← Uses special names for behaviors
│  Runtime      │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Can Python variable names start with a number? Commit to yes or no.

Common Belief: Some people think variable names can start with numbers if they look like numbers.

Reality: Python variable names cannot start with numbers; they must start with a letter or underscore.

Why it matters: Using invalid names causes syntax errors that stop your program from running.

Quick: Do you think naming conventions affect how Python runs your code? Commit to yes or no.

Common Belief: Many believe that following naming conventions changes how the program behaves.

Reality: Naming conventions do not affect program execution; they only help humans read and maintain code.

Why it matters: Ignoring conventions won't break code but makes it harder for others to understand and collaborate.

Quick: Are names with double underscores just normal variables? Commit to yes or no.

Common Belief: Some think names with double underscores are just stylistic choices without special meaning.

Reality: Names with double underscores (dunder) have special meanings and trigger Python's built-in behaviors.

Why it matters: Misusing dunder names can cause unexpected behavior or bugs in your programs.

Quick: Can you use Python keywords as variable names if you add an underscore? Commit to yes or no.

Common Belief: People sometimes think adding an underscore to a keyword makes it a valid variable name.

Reality: Adding an underscore changes the name so it is no longer a keyword and is valid, e.g., 'class_' is allowed.

Why it matters: Knowing this helps avoid naming conflicts while keeping meaningful names.

Expert Zone

1

Leading underscores in names signal intended privacy but do not enforce it; understanding this helps design clean APIs.

2

Name mangling with double leading underscores protects class internals but can confuse beginners if overused.

3

Consistent naming across modules and packages improves discoverability and reduces cognitive load in large codebases.

When NOT to use

Avoid overly strict adherence to conventions in small scripts or quick experiments where speed matters more than style. In some cases, domain-specific naming or legacy codebases require different styles. Alternatives include using camelCase in projects that integrate with other languages or frameworks that prefer it.

Production Patterns

In professional Python projects, naming conventions are enforced via linters and code reviews. Constants are grouped in separate modules. Classes follow PascalCase strictly, and functions and variables use snake_case. Special dunder methods are implemented carefully to customize object behavior. Naming consistency is part of coding standards documented for teams.

Connections

Code Readability

Naming conventions build on the concept of code readability.

Good naming is a foundational practice that directly improves how easily others can read and understand code.

Human Memory and Cognition

Naming conventions align with how humans remember and process information.

Consistent and descriptive names reduce mental effort, making programming less error-prone and more efficient.

Linguistics and Semiotics

Naming in programming relates to how signs and symbols convey meaning in language.

Understanding naming as a form of symbolic communication helps appreciate why conventions matter beyond syntax.

Common Pitfalls

#1 Using Python keywords as variable names.

Wrong approach:

def = 5
print(def)

Correct approach:

def_ = 5
print(def_)

Root cause:

Not knowing that keywords are reserved and cannot be used as identifiers.

#2 Starting variable names with numbers.

Wrong approach:

2count = 10
print(2count)

Correct approach:

count2 = 10
print(count2)

Root cause:

Misunderstanding the rule that names must start with a letter or underscore.

#3 Ignoring naming conventions and mixing styles.

Wrong approach:

UserName = 'Alice'
user_age = 30
MAXsize = 100

Correct approach:

user_name = 'Alice'
user_age = 30
MAX_SIZE = 100

Root cause:

Not realizing that consistent naming styles improve readability and maintainability.

Key Takeaways

Python naming rules define the syntax that makes names valid and prevent errors.

Naming conventions are style guides that make code easier to read and understand by humans.

Variables and functions use snake_case, classes use PascalCase, and constants use UPPERCASE.

Special names with underscores have unique meanings and should be used carefully.

Balancing clarity and brevity in names is a key skill for writing professional-quality code.