Concepts / Writing Readable Code: Style and Conventions

Writing Readable Code: Style and Conventions

Naming conventions are the second check, because readable code should communicate what a value represents.

  • Programming

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.

first characterletter or underscoreremainingcharactersletters, digits, orunderscoreslengthany lengthlegal namePython accepts itthen checkthen considerrules satisfied
Which parts of a variable name determine whether Python accepts it or rejects it?

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.

PatternResultReason
Starts with a letterLegalA letter is allowed as the first character
Starts with an underscoreLegalAn underscore is allowed as the first character
Contains letters, digits, and underscoresLegalThese are the permitted character types
Starts with a digitIllegalA variable name cannot begin with a digit
Contains a spaceIllegalSpaces are not allowed
Contains a hyphenIllegalHyphens are not allowed
Contains another special characterIllegalSpecial characters are not allowed

The first character has a stricter rule than the characters that follow.

letterallowed first characterletterallowed later character_allowed first characterdigitallowed later characterdigitnot allowed first_allowed later charactercan be followed bycan be followed bycan be followed bycan be followed bycan be followed bycan be followed by
Why can a variable name contain digits or underscores after the first character but not begin with a digit?

Testing Candidate Names

Worked example

Checking Three Candidate Names

Decide whether each candidate follows Python's variable-name rules: total_items, 2nd_place, and item-count.

  1. 1
    total_items

    This name starts with a letter and contains only letters and an underscore, so it follows the character rules.

  2. 2
    2nd_place

    This name contains permitted characters, but it starts with a digit. That makes it illegal.

  3. 3
    item-count

    This name starts correctly, but it contains a hyphen. Hyphens are not allowed.

Result

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.

xvague variable nametotal_itemsdescriptive snake_case namereplace with clearer name
How does changing a vague name such as x into a descriptive snake_case name improve the information a reader can infer?
In the real world

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.

total_itemsseparates lowercase words_itemsleading underscoretotal-itemshyphen is not alloweddifferent usedifferent issue
When does an underscore clarify a variable name, and when does it make the name harder to read or violate a convention?
  • Common mistake

    Starting a variable name with a digit

    What it looks like

    2nd_place

    Why it fails

    Python variable names cannot start with a digit.

    Do this instead

    Begin the name with a letter or underscore, then use permitted characters.

  • Common mistake

    Using spaces in a name

    What it looks like

    total items

    Why it fails

    Spaces are not allowed in variable names.

    Do this instead
    Use snake_case, such as total_items.
  • Common mistake

    Using a hyphen as a word separator

    What it looks like

    item-count

    Why it fails

    Hyphens are not allowed in variable names.

    Do this instead

    Use an underscore between words, such as item_count.

  • Common mistake

    Using a vague name when a descriptive name is available

    What it looks like

    x

    Why it fails

    The name is legal but gives readers little information about what the value represents.

    Do this instead

    Choose a descriptive snake_case name, such as total_items, when that meaning is known.

  • Common mistake

    Using a leading underscore for a regular application variable

    What it looks like
    _items
    Why it fails

    Leading underscores are reserved for library code.

    Do this instead

    Avoid a leading underscore in regular applications.

Practice the Naming Check

MEDIUM

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.
  1. 1
    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.

Related Topics

Related concepts

More concepts starting with W