File Naming Conventions (Harvard)

What are file naming conventions?

To maximize access to your records, we recommend establishing a naming convention for your files.

A file naming convention is a framework for naming your files in a way that describes what they contain and how they relate to other files.

File naming conventions help you stay organized and quickly identify your files. In a shared or collaborative group file-sharing setting, it will help others more easily navigate your work.

It is essential to establish a convention before you begin collecting files or data in order to prevent a backlog of unorganized content that will lead to misplaced or lost data!

Example File Names

No naming convention:

• Test data 2016.xlsx
• Meeting notes Jan 17.doc
• Notes Eric.txt
• Final FINAL last version.docx
  

With a naming convention:

• 20160104_ProjectA_Ex1Test1_SmithE_v1.xlsx
• 20160104_ProjectA_MeetingNotes_SmithE_v2.docx
• ExperimentName_InstrumentName_CaptureTime_ImageID.tif

Tips for File Naming

The following tips were adapted from Briney, K. A. (2020, June 2). File Naming Convention Worksheet. California Institute of Technology. This resource was recently awarded a 2023 DataWorks! Prize Significant Achievement Award.

Think about your files

What related files are you working with?

• Identify what group of files your naming convention will cover
• You can use different conventions for different file sets
• Check for established file naming conventions in your discipline or group
  

Example: This convention will apply to all of my microscopy files, from raw image through processed image.

Identify metadata (for example, date, sample, experiment)

What information is needed to easily locate a specific file?

The computer arranges files by name, character by character. Therefore, put the most important information first. If you anticipate wanting to find a file by date, then put the date first. The file name should be descriptive and provide just enough contextual information.

Consider including a combination of the following information:

• Experiment conditions
• Type of data
• Researcher name/initials
• Lab name/location
• Project or experiment name or acronym
• Date or date range of experiment
  • A good format for date designations is YYYYMMDD. This format makes sure all of your files stay in chronological order. To add a timestamp to your filename, use the format YYYYMMDDThhmm.
• Experiment number or sample ID
  • When using a sequential numbering system, use leading zeros for clarity and ensure files sort in sequential order. For example, use "001, 002, ...010, 011 ... 100, 101 ..." instead of "1, 2, ...10, 11 ... 100, 101 ..."
    

Example: For my images, I want to know the date, sample ID, and image number for that sample on that date.

Abbreviate or encode metadata

Don't forget to document any codes!

• Decide what shortened information to keep
• Standardize the categories and/or replace them with 2- or 3-letter codes
• Be sure to document these codes!
  

Example: Sample ID will use a code made up of: a 2-letter project abbreviation (project 1 = P1, project 2 = P2), a 3-letter species abbreviation (mouse = “MUS”, fruit fly = “DRS”), and 3-digit sample ID (assigned in lab notebook).

Use versioning

Are you maintaining different versions of the same file?

• Use versioning to indicate the most current version of a file
• Track versions of a file by adding version information to end of the file name, e.g. filename_v2.xxx
• Use a version number (e.g. “v01” or “v02”)
• Use the version date (use ISO 8601 format: YYYYMMDD or YYYY-MM-DD)

Think about how you will search for your files

What comes first?

• Think about how you want to sort and search for your files in order to determine the order for the metadata in the file name
• Decide what metadata should appear at the beginning
• Use default ordering: alphabetically, numerically, or chronologically
• Use ISO 8601-formatted dates (YYYYMMDD or YYYY-MM-DD)

Deliberately separate metadata elements

Avoid spaces or special characters in your file names

Determine the characters you will use to separate each piece of metadata in the file. Many computer systems cannot handle spaces in file names, so do not use spaces!

• Use dashes (-), underscores (_), or capitalize the first letter of each word
  • Dashes: file-name.xxx
  • Underscores: file_name.xxx
  • No separation: filename.xxx
  • Camel case (the first letter of each section of text is capitalized): FileName.xxx
• Avoid special characters, such as: ~ ! @ # $ % ^ & * ( ) ` ; : < > ? . , [ ] { } ' " |
  

Example: I will use underscores to separate metadata and dashes between parts of my sample ID.

Write down your naming conventions

Include a top-level README file on how to navigate the structure

Naming conventions should be documented so that others in your lab or department can follow this standard. Document naming conventions in a README.txt and keep it with your files!

• If the file is moved or shared, users will be able to identify the file from its file name.
• File names should be 40-50 characters and conventions should only use alphanumeric characters, dashes, underscores
  • If you find that you are encoding a large amount of metadata in the file names, you should consider storing this metadata in a master spreadsheet with your data for future reference.
    

Example: My file naming convention is [SA-MPL-EID]_[YYYYMMDD]_[###]_[status].[tif]

Additional Resources

Get started with naming conventions!

• File Naming Conventions Checklist by the LMA RDMWG
• File Naming Convention Worksheet by Kristin Briney, Caltech Library
• File organization for reproducible research by Data Carpentry