Handbook
Gradient Handbook / Product Team / Coding / Package Development / Variable Naming Rules Edit this page

Variable Naming Rules

This guide explains how we name our code variables at Gradient. This refers to every R script we will ever create. Read through this and adhere to our protocol to improve collaboration! If a script in a Pull Request does not adhere to these naming rules, link to this page and let the coder update the names. This guide is heavily inspired by the Tidyverse Style Guide.

This page is different from “ How we name saved files at Gradient” since this is not about naming saved files, but naming in-script variables.

General

  • Only use lowercased letters, numbers, and underscores ( _ ) in your variable names. Use the clean_names() function from the janitor package.
  • Try to give meaningful names to your variables. This is hard, but very important!
  • Avoid renaming or reusing names for different variables
  • Remove temporary file names from final script!

Data Frames

As detailed in our coding hygiene documentation - we use master data frames and do not filter these, until absolutely necessary.

This changes the way we name our data frames substantially and we should adhere to the following abbreviations to detail the type of data frame that we have

Abbreviation Meaning Usage Examples
# Comment Comment every data frame you create with information about the purpose that it serves. See the most convenient way in the examples customers_orig_df <- # Create original df supplied by client
_df data frame add _df to a variable name if it is a data frame read_csv(customer_file_client.csv)
_raw original add _raw to a data frame when it is first being used (e.g. straight from the client) customers_orig_dftransactions_orig_df
_master master add _master to a data frame if it contains all the data that we need. This is unfiltered and exhaustive for all the information that we have on that particular subject. Every subsequent data frame must be derived from this data frame. customers_master_dftransactions_master_df
_gtd gathered add _gtd if the data frame you created is gathered from master. customers_gtd_df <- # Gather df for xxx
_spd spread add _spd if the data frame you created is spread from master. customers_spd_df <- # Spread df for xxx
_ftd filtered add _ftd if the data frame you created is a filtered version from master. customers_ftd_df <- # Create filtered df for xxx
_mtd mutated add _mtd if you added or changed columns. customers_mtd_df <- # Create mutated df for xxx
_smd summarized add _smd if you created summary statistics customers_smd_df <- # Create summary statistics df for xxx
xjoin‘otherdf’ l = left_joinr = right_joini = inner_joins = semi_joina = anti_joinf = full_join add _xjoin if the data frame you created is a join between two existing data frames. Add the name of the second data frame too. customers_ljoin_transactions_df <- # Left join transactions_orig_df with customers_orig_dfcustomers_fjoin_transactions_df <- # Full join transactions_orig_df with customers_orig_df
_gtd_spd_mtd_ljoin_df Combinations If you have combinations of the above, add all that apply. Make sure to add a comment supplying the purpose of the df customers_mtd_ftd_spd_df <- # Derived data frame to work the same data in a wide format
_smpl sample add _smpl if your data frame is a sample of the master data frame. Always add a seed if you sample, and explain why the sample is necessary customers_smpl_df
_temp temporary add _temp if the data frame you created is only temporary and should not exist beyond the development phase customers_temp_df <- # Temporary df for testing xxx
_dv_x deliverable for x add _dv if the data frame you created is a project deliverable. Is different in the way that it adds more detail to column names and is client presentable ready customers_dv_contactablitiy_df <- # Deliverable for xxx

Constants

  • Constants are defined as variables that hold a single value (e.g. the exchange rate from dollar to yen)
  • Must be written in ALL_CAPS as the only exception to the global lower-case rule.
  • If it details an argument to a function call, add the function name as a suffix.

Examples

Constants

Constants:

EXCHANGE_RATE <- 0.004

TODAY <- Sys.Date()

Function Constants:

K_KMEANS <- 8

K_KNN <- 12

kmeans(k = K_KMEANS, ...)

knn(k = K_KNN, ...)

Other variables

  • Should be nouns
  • Should be concise
  • Suffix your variable with the variable type (e.g. xxx_plot | xxx_model | xxx_list)

Examples

Variable Names

Good variable names

  • customer_scores_glm_model
  • product_metadata_list
  • customer_segmentation_dendogram_plot

Bad variable names

  • cust_history <- we don't know the type
  • cust_glm <- vary vague
  • another_cust_glm <-
  • plot.xvar <- Don't use dots in variable names

Functions

  • Should be verbs
  • Should explain what the function does.
  • Must have a comment line prior to the function explaining the purpose!

Examples

Function Names

Good function names

  • score_customers_expected_spend()
  • add_mean_transaction()
  • parse_noun()
  • extract_metaphor()
  • scrape_twitter()
  • clean_tweets()

Bad function names

  • score_customers() <- Doesn't detail what it scores the customers on
  • noun_parser() <- Not a verb
  • noun.parser() <- Don't use dots
  • metaphor_extraction() <- Not a verb
  • Scrape_Twitter() <- Don't use capital letters