Naming Convention

Variable Naming Conventions

A variable can have a short name (like x and y) or a more descriptive name (like age, carname, total_volume). Rules for Python variables:

• A variable name must start with a letter or the underscore character
• A variable name cannot start with a number
• A variable name can only contain alpha-numeric characters and underscores (A-z, 0-9, and _ )
• Variable names are case-sensitive (age, Age and AGE are three different variables)
• The reserved words (keywords) cannot be used naming the variable
• Variable names should be short but descriptive
• Use of underscores (_) is recommended to improve readability
• Avoid using special characters like !, @, #, $, %, etc. in variable names
• Avoid using built-in function names as variable names
• Avoid using single characters like l, O, I, etc. as variable names
• Avoid using words with double meaning like list, str, dict, etc. as variable names
• Avoid using words with different spellings like colour and color, centre and center , etc. as variable names

Example:

variable.py

# Valid variable names
name = "John"
my_name = "John"
_my_name = "John"
myName = "John"
MYNAME = "John"
myname = "John"
myName2 = "John"
my2name = "John"

Caution

Python is a case-sensitive language. This means that my_name and myName are two different variables.

Caution

Don’t use long variable names. Use short names instead. This improves readability and reduces the amount of typing.

variable.py

# Don't recommend
my_name_is_john_and_i_am_20_years_old = "John"

Danger

You cannot use Python keywords as variable names. Keywords are the reserved words in Python. They are used to define the syntax and structure of the Python language. You can’t use them as variable names.

variable.py

# Invalid variable names
class = "John"
for = "John"
# Some other Invalid variable names
2myname = "John"
my-name = "John"
my name = "John"

Constant Naming Conventions

Constants are usually declared and assigned in a module. Python does not have built-in constant types, but Python programmers use all capital letters to indicate a variable should be treated as a constant and never be changed after it is initialized.

Example:

constant.py

# Valid constant names
PI = 3.14
GRAVITY = 9.8
PLANET = "Earth"

Function Naming Conventions

Function names should be lowercase, with words separated by underscores as necessary to improve readability. Mixed case is allowed only in contexts where that’s already the prevailing style (e.g. threading.py), to retain backwards compatibility.

Example:

function.py

# Valid function names
def my_function():
    pass
 
def myFunction():
    pass

Class Naming Conventions

Class names should normally use the CapWords convention.

Example:

class.py

# Valid class names
class MyClass:
    pass

Naming Convention Standards

Python has a set of naming conventions for different types of identifiers. These conventions are defined in PEP 8 — Style Guide for Python Code, which is the style guide that most Python projects follow.

There are different naming styles for different types of identifiers. The following table summarizes the naming conventions for different types of identifiers:

Camel Case

Starts each word with a capital letter except the first word. For example: firstName, lastName, getFirstName(), setFirstName(), etc.

variable.py

# Camel Case
firstName = "John"
lastName = "Doe"
def getFirstName():
    pass
def setFirstName():
    pass

Pascal Case

Starts each word with a capital letter. For example: FirstName, LastName, GetFirstName(), SetFirstName(), etc.

variable.py

# Pascal Case
FirstName = "John"
LastName = "Doe"
def GetFirstName():
    pass
def SetFirstName():
    pass

Snake Case

Uses underscores (_) between words. For example: first_name, last_name, get_first_name(), set_first_name(), etc.

variable.py

# Snake Case
first_name = "John"
last_name = "Doe"
def get_first_name():
    pass
def set_first_name():
    pass

Which Style Does Python Use?

The three styles above all run, but Python’s official style guide (PEP 8) assigns a specific style to each kind of identifier. Following it makes your code look like everyone else’s Python.

Identifier	Convention	Example
Variable	snake_case	user_age, total_price
Function	snake_case	get_user(), calc_total()
Constant	UPPER_SNAKE_CASE	MAX_SIZE, PI
Class	PascalCase (CapWords)	BankAccount, UserProfile
Module / file	short lowercase	utils.py, data_loader.py

Tip

camelCase is not idiomatic Python even though it works. Use snake_case for variables and functions — reserve PascalCase for classes.

Underscore Conventions

The underscore carries special meaning in several naming patterns:

Pattern	Meaning
_name	“Internal use” hint — a weak private signal to other developers.
name_	Trailing underscore to avoid clashing with a keyword, e.g. class_, type_.
__name	Name mangling inside a class — Python rewrites it to avoid subclass clashes.
__name__	“Dunder” (double underscore) — reserved for Python, e.g. __init__, __name__.
_	A throwaway variable for values you intend to ignore: for _ in range(3):.

underscores.py

_internal = "use within this module"
class_ = "Biology 101"     # avoids the 'class' keyword
for _ in range(3):         # loop counter is unused
    print("hi")

Note

For the full rules, see PEP 8 — Style Guide for Python Code.

---

Underscores are a language feature, not only a style

Three of the four underscore conventions are pure convention. One of them changes what the compiler does:

diagram Diagram mermaid

  flowchart TD
  N["attribute name"] --> Q{"leading underscores?"}
  Q -->|"name"| P["public
convention only"]
  Q -->|"_name"| I["internal
convention only
hidden from 'from m import *'"]
  Q -->|"__name"| M["NAME MANGLED by the compiler
becomes _ClassName__name"]
  Q -->|"__name__"| D["dunder: reserved for Python
NOT mangled"]

mangling.py

class C:
    def __init__(self):
        self.public = 1
        self._internal = 2
        self.__private = 3
 
c = C()
print(list(vars(c)))     # ['public', '_internal', '_C__private']
c.__private              # AttributeError
c._C__private            # 3

The attribute was renamed at compile time to _C__private. This is not access control — the value is trivially reachable — it is collision avoidance, so a subclass defining its own __private cannot clobber the parent’s.

Two underscores is rarely what you want

Use a single _name to mean “internal, do not rely on this”. Reserve __name for the specific case where a subclass might reasonably choose the same attribute name and you need both to survive. Mangling also makes debugging and testing harder.

Reserved, soft-reserved, and merely conventional

keywords.py

import keyword
 
len(keyword.kwlist)              # 35 hard keywords: def, class, if, ...
keyword.softkwlist               # ['_', 'case', 'match', 'type']
keyword.iskeyword("match")       # False  <- a SOFT keyword; usable as a name
keyword.iskeyword("def")         # True   <- `def = 1` is a SyntaxError

There are 35 hard keywords you cannot use as names, and four soft keywords that are only special in context — match and case are ordinary identifiers everywhere else, which is how match could be added without breaking existing code.

See it move

Type-check a name against the rules Python actually enforces, and the ones PEP 8 merely recommends. Click a name to see which of each it satisfies.

sketch What Python enforces, and what PEP 8 suggests p5.js Pause Restart

Only two rules are enforced by the language: the character set and the keyword list. Everything about casing is convention that tools check, not the interpreter.

Identifiers are normalised before they are compared

This one surprises almost everyone. Python applies NFKC normalisation to identifiers, so two different sequences of characters can be the same name:

nfkc.py

import unicodedata
unicodedata.normalize("NFKC", "\ufb01")     # 'fi'  — the ligature becomes two letters
 
# a name written with U+FB01 (the 'fi' ligature) is reachable as plain ascii 'fi'

A variable written with the typographic ligature fi and one written fi are the same variable. Not every lookalike normalises, though — the dotless ı (U+0131) stays distinct from i.

Why this matters for code review

Two identifiers can render identically in your editor and be different names, or render differently and be the same name. Any project accepting outside contributions should restrict identifiers to ASCII — most linters have a rule for it.

The conventions worth following

kind	convention	example
variable, function	lower_snake_case	user_count, parse_row
constant	UPPER_SNAKE_CASE	MAX_RETRIES
class	CapWords	HttpClient
internal	_leading_underscore	_cache
avoid a keyword clash	trailing_underscore_	class_, id_
module	short lowercase	utils, http

Note the last row of the previous section: shadowing a builtin such as list, id, type or sum is perfectly legal and never warns. class_ with a trailing underscore is the documented way to name something that would otherwise collide.

Check yourself

pch.quizTag pch.quizDefaultTitle

1. Inside class C, you assign self.__private = 3. What key appears in vars(instance)?

   A __private B _private C _C__private D private
   pch.quizShowAnswer

   C — _C__private — The compiler mangles a double-underscore name to _ClassName__name. It exists to stop a subclass accidentally reusing the same attribute name, not to enforce privacy — _C__private is readable by anyone.

2. Which of these is a SOFT keyword, meaning it is reserved only in certain positions?

   A class B match C return D lambda
   pch.quizShowAnswer

   B — match — match, case, type and _ are soft keywords: special inside a match statement and ordinary identifiers elsewhere. That is how match could be added without breaking code that used it as a variable.

3. A contributor submits code where a name is written with the typographic ligature for 'fi'. What does Python do?

   A rejects it with a SyntaxError B treats it as a distinct identifier from the ascii spelling C normalises identifiers with NFKC, so it is the SAME name as the ascii spelling D accepts it only inside string literals
   pch.quizShowAnswer

   C — normalises identifiers with NFKC, so it is the SAME name as the ascii spelling — Identifiers are NFKC-normalised, so the ligature becomes 'fi'. Two names can look different and be identical — a reason to restrict identifiers to ASCII in projects taking outside contributions.

4. Which naming rule does the interpreter actually enforce?

   A constants must be written in ALL_CAPS B classes must use CapWords C a name may not start with a digit and may not be one of the 35 reserved keywords D functions must use snake_case
   pch.quizShowAnswer

   C — a name may not start with a digit and may not be one of the 35 reserved keywords — Only the character set and the keyword list are enforced. Every casing rule is PEP 8 convention, checked by linters rather than by the interpreter.

Try it: Naming Convention Exercises

Exercise 1 – Valid Variable Names

pch.exerciseTag pch.exerciseTitle

Exercise 2 – Constants in UPPER_CASE

pch.exerciseTag pch.exerciseTitle

Exercise 3 – CamelCase for Classes

pch.exerciseTag pch.exerciseTitle