Make Your Code Easier to Read Using Expressive Variable Names in Python#

What you will learn

  • Learn how using expressive names can help you write clean and readable code.

  • Create expressive names for objects in your Python code.

  • Describe the PEP 8 recommendations for Python object names.

Why use expressive names?#

Expressive names describe the contents of the object itself. So for example you probably expect a directory called data to contain data within it.

File and directory names that clearly indicate the type of information stored within that file or directory are the most useful or expressive to your colleagues or your future self as they allow you to quickly understand the structure and contents of a project directory.

Compare the list of file names on the LEFT to those on the right - which ones are easier to quickly understand? File and directory names that clearly indicate the type of information stored within that file or directory are the most useful or expressive to your colleagues or your future self as they allow you to quickly understand the structure and contents of a project directory. Source: Jenny Bryan, Reproducible Science Curriculum.#

Expressive code is also important for naming variables and functions in your Python code because it will make your code easier to understand for someone skimming it, just as it makes it easier for someone to understand a file directory structure.

Expressive code is another part of clean coding - that is, writing code that is easier for you, your future self, and for someone else to look at and understand. After you’ve been programming for a while, you will begin to see that consistently formatted code is much easier for your eye to scan and quickly understand.

alt here.

This container clearly contains cookies, yet it’s labeled “rice.” This might be confusing to someone who is looking for rice in your kitchen! Consider this when writing code. It’s easier for someone to understand your code without running it when your code variables describe the objects that they contain. Source: Jenny Bryan, Reproducible Science Curriculum. ::#

Tip

The the PEP 8 Style Guide suggests that all objects (variables, functions and methods) in your code are named using meaningful words.

Best practices for naming objects#

PEP 8 style guide has a suite of recommendations that focus on making Python code more readable. Below are some of the PEP 8 guidelines related to expressive object names.

  1. Use meaningful names: A meaningful or expressive variable name will be eaiser for someone to understand. For example: precipitation is a more useful name that tells us something about the object compared to x or a.

  2. Keep object names short: this makes them easier to read when scanning through code.

  3. Do not start names with numbers Objects that start with a number are NOT VALID in Python.

  4. Avoid names that are existing functions in Python: e.g., if, else, for, see here for more reserved names.

A few other notes about object names in Python:

  • Python is case sensitive (e.g., weight_kg is different from Weight_kg).

  • Avoid existing function names (e.g. mean), though you can combine these with other words to create a more descriptive name (e.g. precip_mean).

  • Use nouns for variable names (e.g. weight_kg), and verbs for function names (e.g. convert_kg_lb).

  • Avoid using dots in object names - e.g. precip.boulder - dots have a special meaning in Python (for methods - the dot indicates a function that is connected to a particular Python object) and other programming languages.

    • Instead, use underscores for snake case: precip_boulder.

Recommendations for naming conventions#

Best practices for directory and file names#

We suggest that you use directory and file names that contain words that describe the contents of the file or directory, separated using underscores _ like this:

snake_case_with_underscores

While you may see dashes - sometimes in directory names (lower-case-with-dashes) when working with JavaScript, dashes are not valid for Python module names, variables, or functions.

Directory and files names should be kept as short and concise as possible, while also clearly indicating what is contained within the directory or file.

Best practices for Python variable names#

For variables, we suggest that you use lowercase for short variable names and lower_case_with_underscores for longer and more descriptive variable names. Variable names should be kept as short and concise as possible while also clearly indicating the kind of data or information contained in the variable.

Examples include:

  • precipitation: to indicate a simple variable (either single value or data structure without temporal or spatial variation in coverage)

  • boulder_precipitation: to indicate the location of the data collection

  • max_precipitation: to indicate the result of a summary statistic

  • precipitation_2002: to indicate a particular year of data included

  • precipitation_2002_2013: to indicate the particular years of data included

  • precipitation_2000_to_2010: to indicate a range of years of data included

  • precipitation_inch or precipitation_mm: to indicate the measurement units

The variable names should be driven by the overall goals and purpose of the code in which they are being used.

For example, in some cases, it may be more important to distinguish the units of measurement, the location, or the year or range of years covered by the data. Use your best judgment and modify variable names as needed.

Best practices for naming Python functions and methods#

Following PEP 8 guidelines, function names should be formatted using
words_separated_by_underscores. The words that you use to name your function should clearly describe the function’s intent (what the function does). Ideally this name is a very specific name that describes what the function does. For example, if you write a function that removes hyphens from some text a name like remove_hyphens might be appropriate.

## This function name is less expressive 
text_edit()

# This function name is more expressive
remove_hyphens()

Example function#

The function below is designed to convert a temperature provided in a numeric format in degrees Fahrenheit to Kelvin.


def convert_to_kelvin(temperature_fahr):
    """Convert temperature in Fahrenheit to kelvin.
    
    Parameters:
    -----------
    temperature_fahr: int or float
        The temperature in Fahrenheit.
    
    Returns:
    -----------
    The temperature in kelvin.
    """
    return ((temperature_fahr - 32) * (5 / 9)) + 273.15

Consider the list of function names below for the above function, which of these names are the most expressive and why?

f()
my_func()
t_funk()
f2k()
convert_temperature()
fahr_to_kelvin()

Tip

PEP 8 suggests that class names should use mixedCase.