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 Plays Well With Default Ordering

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

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

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

Follow three principles!

1 Machine-Readable

2 Human-Readable

3 Plays Well With Default Ordering

1 Machine-Readable

Goal

- Characters in file names are handled correctly by all computer systems.
- Names are brief and easily searchable. 

Only use the following:

Alphanumeric characters (alphabetic characters and Arabic numerials)

Element delimiters: _(underscore)
Word delimiters (within an element): -(dash) and/or capitalize the first letter of each word (camel case)
e.g. [element 1]_[element 2]_[WordPart-WordPart-WordPart]_[element 3].txt

Avoid spaces and other special characters, such as: ~ ! @ # $ % ^ & * ( ) ` ; : < > ? . , [ ] { } ‘ “ |

Make sure to do the following:

If you decide to abbreviate the elements with 2- or 3-letter codes (e.g. project 1 = P1, mouse = “MUS”), make sure these are well documented.
Keep case sensitivity in mind - Machine searching for files named “Scan” would not find files named “scan”.

Exercise 1

Let’s try improve the file names! Pick your favourite file name and make it more machine-readable!

2 Human-Readable

Goal

- File names provide concise information.  
- Names are easily understandable to anyone who accesses them in future.

Provide essential information concisely in the file name

Ideally 3 elements, 5 max.
Avoid complex hierarchical folder structures.

Consider putting authors’ names in the file name. Put family names first followed by first names or initials.

Write down your naming convention pattern and document it in your README file.

e.g. My file naming convention is [SA-MPL-EID]_[YYYY-MM-DD]_[###]_[status].[txt]
Define acronyms, abbreviations and codes.

3 Plays Well With Default Ordering

Goal

- Names start with the element that is used to order the files.
- Version information is at the end.

Decide the beginning of the file name according to how you want to sort and search for your files.
When using a sequential numbering system, use leading zeros to make sure files sort in sequential order. e.g. 001, 002, 010, 011….100,101 …
Order elements from general to specific to make searching easier
Use ISO 8601 standard for dates: YYYYMMDD or YYYY-MM-DD
Versions: should be used as the last element
- For version numbers, use at least two digits with a leading zero (e.g. v0)
- Version types (e.g. _raw, _processed, _composite)

Exercise 2

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

Please create a file naming convention for these files to reflect what you have learned about file naming in today’s session.

Congrats!

Now you know how to organize files with your own file naming conventions! As long as your names are clear and consistent, you are good to move forward!

Sources

Need help?

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