File naming

Carefully choosing file names that are informative and useful for both humans and machines is a simple step towards reproducible research. The more meaningful the name the easier it will be for others to understand what the file contains and how it should be used.

Choose machine readable names

Use deliberate deliminators

  • Common approach is using “_” and “-” to deliminate units of metadata in the file names.
  • Can use “-” to separate words you want to glob together and “_” to separate different information within a file name.

Don’t use spaces, punctuation, or capital letters

Don’t use special characters

  • Using $, @, %, #, &,*, (, ), !, etc. may have meanings in programming languages.

Choose human readable names

Choose names that explain the content

  • The more meaningful the name, the more useful it is for human users.
  • The more metadata you store in the name, the less you need to explain elsewhere.

Choose short names

Replace files with same name for version control

If you are using the OSF, uploading a new file with the same name as an existing file will replace the existing file. A downloadable copy of the replaced file will be saved via Revisions beneath the Files tab.

This is called version control and helps to track the changes to files, document who and when changes were made, and reduce file version conflicts. More documentation on version control may be found here. If you are not using version control, you can track versions by choosing file names that use default ordering.

Choose names that use default ordering

When not employing version control, a number a methods facilitate file ordering and distinction.

Don’t use the word “final”

  • Number or date the versions so they can be ordered.

Put something numeric first

  • A date or version number is common.
  • Left pad version numbers with zeros (eg, 01_file.pdf).

Use YYYY-MM-DD for dates

  • The computer will order using this date format.