Why is file naming important?

Creating a well-organized hierarchy of files with clear naming conventions is an important part of improving your research process. This is especially important if you are working with large data sets and complex output files or coordinating with multiple people at multiple institutions. There are many ways to structure your folders, and multiple naming conventions you can use. The key is consistency. Make your file names descriptive, and include information about dates and versioning. The best practice is to consult with your lab or with your co-workers to develop a naming schema that everyone is willing to follow consistently.

Looking for a cheat sheet? Check out our one-pager!

Table of Contents

1 Machine-Readable
2 Human-Readable
3 Supports Default Ordering

Warm up!

What do you think about the following file names?

10_data 2.txt
figure 1.png
final revision.docx
Lily’s schedule&plan 2022Jul9.xlsx

Are these names better?

better-filenames.txt
003_raw-data_2022-07-09.txt
fig01_scatterplot-talk-length-vs-interest.png
20220709_interview-script_v01.docx

This is what happens when you do not have effective naming conventions:

We will see very shortly why effective naming conventions are a necessity!

Follow these three principles!

1 Machine-Readable

2 Human-Readable

3 Supports Default Ordering

1 Machine-Readable

Goals:

Characters in file names are handled correctly by all computer systems
Be consistent with the chosen naming convention

For files to be machine-readable, use the following:

Alphanumeric characters: Latin alphabetic characters and Arabic numerals
Snake case: use _ underscores to separate words and numbers
- this_is_snake_case
Camel case: use capitalization to separate words and numbers
- thisIsCamelCase
Hyphens: use – hyphens to separate words and numbers
- this-is-using-hyphens
Avoid spaces and other special characters, such as: ~ ! @ # $ % ^ & * ( ) ` ; : < > ? . , [ ] { } ‘ “ |
- Certain special characters are used by operating systems to perform tasks. This makes it difficult for the machine to read the file names
Be mindful of case sensitivity
- Some operating systems may search for file names of a certain case

Be consistent:

The way you name your file should be consistent
The style you choose should be based on conventions adopted in a given project, organization, language, etc.
- Example: R and Python use snake case, so file names and folder names should follow this convention

Exercise 1

Let’s improve these file names using what we’ve learned so far! Pick a file and rename it to make it more machine-readable.

What did you change and why?

2 Human-Readable

Goals:

Consistency
Intelligible to humans
Concise yet descriptive

For files to be human-readable, consider the following:

Have file names that follow a consistent naming method, and document this file naming method in your README file
- Especially if acronyms, abbreviations, and/or codes are used, you should define what they mean in your README file
The file names should be concise but detailed enough so that they’re still understandable to you and anyone else who has access
- Names shouldn’t be too long
- This is especially important for the future!
Avoid including application (software) details in your file names
- Example: you don’t need to add “doc” to your file name of a text document
Overall, the amount of detail is up to you, but we recommend having 3 to 5 elements per file name

Examples:

# not good
a.txt

# too much information
ubc_application_letter_for_institution_position_firstname_lastname_final_date.txt

# okay but can be a more detailed
application.txt

# not amazing, a bit too much detail
clean_data_py_script.py

# good, just enough detail
ubc_application_letter.txt

# good
clean_data.py

3 Supports Default Ordering

Goals:

Decide at the beginning how you want to sort and search for your files to ensure a good hierarchical directory structure:
- Chronological order
- Logical order
Versioning and version types should be added as the last element

Chronological order

Use ISO 8601 standard: YYYYMMDD or YYYY-MM-DD for consistent formatting and correct interpretation of dates

Sorting your files chronologically (having the date as the first name element) may look like this:

2024-01-01_subject_1_results.xlsx
2024-01-01_subject_2_results.xlsx
2024-02-01_subject_1_results.xlsx
2024-02-01_subject_2_results.xlsx

Logical order

When using a sequential numbering system, use leading zeros to make sure files sort in sequential order
- Examples: 001, 002, 010, 011… 100,101 …
We recommend ordering elements from general to specific to make searching easier

Sorting your files logically (using leading zeros) may look like this:

00_innit.R
01_read_data.R
02_clean_data.R
03_model.R
04_visualize.R
helper01_load_variables.R
helper02_functions.R

Versioning and Version Types

Adding a version to the file name should be the last element.

Use at least 2 digits with a leading zero for the version number, and/or indicate the version type.

Version number examples: V01, V03, etc.
Version type examples: _raw, _processed, _composite, etc.

Exercise 2

Your lab has a spectrometer that measures thermal emissions once a day for a year for your experiment. There are three people who take that measurement in the lab.

Have a try at creating a file naming convention for these files to reflect what you learned about today’s session.

How did you structure your file names and why?

Here is a breakdown of what we covered: File names should be machine-readable: use alphanumerical characters with snake or camel case, and don’t have spaces or special characters. File names should also be human-readable: clear, concise, and follow a consistent naming method. Lastly, a good file naming convention helps with sorting and searching your files.

Congrats!

Hooray! Now you know how to organize files with your own file naming conventions.

Sources

Need help?

Please reach out to research.data@ubc.ca for assistance with any of your research data questions.