3  Naming conventions

When naming folders and files, use consistent and clear names that are findable and understandable by both humans and computers. A file name should convey what it contains and which file is the most recent version.

3.1 Why are conventions important?

• Improves consistency and predictability, making it easier to browse folders and know what they contain.

• Enables sorting files by date, conservation district, or another theme.

• Facilitates collaboration so all team members can find the information they need.

• Standardizes file paths and URLs for efficient programming and website hosting.

  • URLs and programming languages are case-sensitive. WaSHI-data.csv and washi-data.csv are completely different files.

  • URLs cannot have spaces in them. They must be escaped with this character entity %20. For example, wasoilhealth.org/producer spotlights would need to be wasoilhealth.org/producer%20spotlights.

For more web-specific naming conventions, see this Learn the Web webpage.

Documents, Randall Munroe’s xkcd

3.2 Best practices

Some files and folders in our shared drive do not follow these best practices or naming conventions. We are learning and improving as we go.

These are just guidelines. Because naming things is hard, we only ask that you try your best. If you’re unsure about names or adding externally named files, the Data Scientist can support you.

See Section 3.3 for a table of examples of folder and file names following these best practices.

Meaningful name casing

Different conventions work for different purposes (folders and files versus programming objects).

• kebab-case: all lowercase with hyphens separating words. Use for folders and files.

• snake_case: all lowercase with underscores separating words. Only use for column names in spreadsheets and code, such as functions and variables in R. See Section 9.2.3.1 for example R errors when including hyphens in object names.

Artwork by Allison Horst

Delimiters convey meaning

Deliberately use underscores and hyphens so we can easily understand the contents and programmatically parse file and folder names.

• Use underscores to delineate metadata elements (i.e. date from name from version date_name_version).

• Use hyphens to separate parts of one metadata element (i.e. date YYYY-MM-DD or name wsda-washi-presentation).

No spaces or special characters

Avoid spaces and special characters (only use underscores and hyphens). Characters like / () ! ? % + " ' have special meaning to computers and can break file paths and URLs.

Character length matters

Computers are unable to read file paths and file names that surpass a certain character length. Be concise AND descriptive. Omit prepositions and articles when possible. Abbreviate long words. The path limit on Windows is 260 characters.

‘Back to front’ date

Express date ‘back to front’ like YYYY-MM-DD according to the ISO 8601 standard. Left pad single-digit months and days with zeros to maintain chronological order of records when sorting alphanumerically.

✅ Do this	❌ Don’t do this
2020-05-28_agenda.pdf	2-14-2023_Agenda.pdf
2023-01-01_agenda.pdf	2023-Jan-1_Agenda.pdf
2023-02-14_agenda.pdf	Dec052020_Agenda.pdf
2023-12-05_agenda.pdf	May_28_2020_Agenda.pdf

Group & sort files by name

Consider how folders and files should be grouped and sorted, and include the appropriate metadata at the beginning of the file name. See examples below.

Sort by district	Sort by date
cowlitz_coc_2023-05-01.pdf	2023-05-01_cowlitz_coc.pdf
cowlitz_coc_2023-05-23.pdf	2023-05-01_cowlitz_tracking.pdf
cowlitz_tracking_2023-05-01.pdf	2023-05-09_ferry-cd_tracking.pdf
ferry-cd_coc_2023-05-10.pdf	2023-05-10_ferry-cd_coc.pdf
ferry-cd_coc_2023-05-17.pdf	2023-05-17_ferry-cd_coc.pdf
ferry-cd_coc_2023-06-06.pdf	2023-05-23_cowlitz_coc.pdf
ferry-cd_tracking_2023-05-09.pdf	2023-06-06_ferry-cd_coc.pdf

Version numbers

Including the date in the file name is one way to version a file. Alternatively, or in addition to, append a number. Consider how many possible versions there could be. If more than 10, use leading zeros so the numbers have the same length. v1 through v15 will not sort the same way as v01 through v15.

✅ Do this	❌ Don’t do this
sop_v01.pdf	SOP_v1.pdf
sop_v02.pdf	SOP_v10.pdf
… [v03 - v09]	SOP_v11.pdf
sop_v10.pdf	SOP_v2.pdf
sop_v11.pdf	… [v3 - v9]

Collaboration

Add your initials to the end of the file name when “saving as” a file that multiple people are working on (i.e., 2023_sop-soil-health-monitoring_lm-jr.docx). This ensures a version is kept as a backup. Alternatively, use Track Changes if working in a MS Word document.

Literature and references

When saving journal articles, user guides, and other reference materials, use the convention author_year_abbreviated-title. Use underscores to separate different metadata.

✅ Do this	❌ Don’t do this
lal_2004_soil-c-to-mitigate-cc.pdf	lal-2004-soil-c-to-mitigate-cc.pdf
clark-et-al_2020_pmn-sampling	clark-et-al_2020_pmn-sampling

Column names and code

Naming conventions for data column headers differ from folders and files. The hyphens in kebab-case cause errors in R and SQL code. Additionally, hyphens, spaces, and other special characters are invalid for ArcGIS table and field names.

Use snake_case for column names in spreadsheets and code objects (R vectors, lists, dataframes, and functions).

In variable or parameter names, include the measurement with the unit. This prevents unit confusion and reduces the risk of misinterpreting or inappropriately using the data.

Do not use special characters. Instead of toc_%, use toc_percent.

Note

The code naming convention here applies primarily to R. Python and other programming languages have different conventions.

See Chapter 9 for more details in the code style guide.

3.3 Naming examples

	Naming convention	Examples
Folders	kebab-case	2024_sampling data-management
Files	kebab-case	2023-11-15_survey-perennial.xlsx 2024-03_washi-newsletter-wsda-sos.docx geisseler-et-al_2019_ace-protein.pdf washi-logo-color.png washi-dmp.Rproj 01_load-metadata.R 2024_producer-report.qmd
Column Names & Code	snake_case	sample_id pmn_lb_ac crop_summary assign_quality_codes()

Documents, Randall Munroe’s xkcd Artwork by Allison Horst