Names

library(gerp)

“It ain’t what they call you, it’s what you answer to.” - W.C. Fields

Files

The names for files and folders come from Jenny Bryan’s excellent ‘Naming things’ slides

Naming files

Below I’ll cover how these principles are implemented in ger_fname()

1. Machine readable: file names should be useful to program with, i.e., easy to search and filter, avoid reliance on case, accented characters, white space, etc.

ger_fname() will convert all names to lower kebab-case and add a date prefix.

ger_fname("My File.txt")

✔ '2023-04-09_my-file.txt' is copied to the clipboard!

2. Human readable: File names should be named similar to URLs. Specifically, the portion of the URL that “is usually the end part of the URL (specifically of the path / pathinfo part), which can be interpreted as the name of the resource, similar to the basename in a filename or the title of a page” is referred to as the slug for brief description of file contents).

ger_fname() removes special characters (but keeps words):

ger_fname("%Joe's%crazy*!$#FILE%name.xlsx")

✔ '2023-04-09_joes-crazy-file-name.xlsx' is copied to the clipboard!

3. Easily sorted/ordered: If a logical order for the files in a directory exists, the filenames should include a numeric prefix that contains the inherent order, with sufficient left-side padding (i.e., `01-import.R`, `02-wrangle.R`, `03-model.R`, etc.).

ger_fname() conserves numeric prefixes (and appends a date prefix):

ger_fname("01-report.xlsx")

✔ '2023-04-09_01-report.xlsx' is copied to the clipboard!

Summary

gerp names have the following format:

All file names should be lower kebab-case, with no white space
A date prefix is appended to all files for provenance, with a trailing underscore (YYYY-MM-DD_). The underscore makes it distinguishable from rest file name:

Special characters and punctuation (outside the file extension) are removed

gerp::ger_fname("Some===crazy???long:::file;name.csv")

✔ '2023-04-09_some-crazy-long-file-name.csv' is copied to the clipboard!

Objects

Names for R objects come from the tidyverse style guide. New users to R can find names confusing when choosing what to name R objects vs. names for R project files. The principles for naming files covered above can (and arguably should) be adopted to make file organization easier and more uniform. However, some of these principles can’t be applied to R objects.

Naming objects

Below I’ll cover the style guide’s advice on object names and how they are implemented in ger_name().

1. Only use lowercase letters, numbers, and underscores (i.e. `snake_case`)

ger_name() converts all characters to snake_case

gerp::ger_name("MY DATA")

✔ 'my_data' is copied to the clipboard!

In the event the object name starts with a number, ger_name() places these at the end of the name

gerp::ger_name("2022 DATA")

✔ 'data_2022' is copied to the clipboard!

Pure numbers will automatically converted to num_var

gerp::ger_name("2022")

✔ 'num_var' is copied to the clipboard!

Any object names that start with special characters or punctuation are also altered to be accetable

gerp::ger_name("__my data__")

✔ 'my_data' is copied to the clipboard!

2. Avoid using dots (i.e., `my.object`)

dots are assumed to contain some inherent meaning to the object name, so dots are replaced with underscores

gerp::ger_name("patient.data")

✔ 'patient_data' is copied to the clipboard!

Unless the name has trailing dots (these are preserved in the event they belong to a meaningful file extension)

gerp::ger_name("---patient/data.csv")

✔ 'patient_data_csv' is copied to the clipboard!

3. Be concise and meaningful (i.e., not `first_day_of_the_month`, but rather, `day_one`)

If the object has a long name, set abbr to TRUE to reduce it’s length to 18 characters

gerp::ger_name("first_day_of_the_month", abbr = TRUE)

✔ 'first_dy_f_th_mnth' is copied to the clipboard!

Additional features

ger_name() replaces the following symbols with abbreviations:

gerp::ger_name("~ ! @ # $ % ^ & * — = +")

✔ 'tilde_bang_at_num_dollar_perc_hat_and_ast_emdash_equals_plus' is copied to the clipboard!

pk > It also reorganizes names with numbers prefixes:

ger_name("20 % of this & that")

✔ 'perc_of_this_and_that_20' is copied to the clipboard!

ger_name() converts just about any string of characters into something that can be assigned to R variables.

ger_name("123456 ! bingo + bongo")

✔ 'bang_bingo_plus_bongo_123456' is copied to the clipboard!

To ensure the names aren’t too long or repeat terms, ger_name() won’t repeat symbols

gerp::ger_name("... !! ++")

✔ 'dot_bang_plus' is copied to the clipboard!