From 7c8f695c821a985a7d6ab2fe623163a229fa8108 Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Wed, 19 Feb 2025 08:04:30 -0600 Subject: [PATCH 1/3] Improve file naming with advice from R4DS https://r4ds.hadley.nz/workflow-scripts.html#saving-and-naming --- files.qmd | 71 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 54 insertions(+), 17 deletions(-) diff --git a/files.qmd b/files.qmd index ba03cac..660cdb6 100755 --- a/files.qmd +++ b/files.qmd @@ -2,37 +2,74 @@ ## Names -File names should be meaningful and end in `.R`. Avoid using special characters -in file names - stick with numbers, letters, `-`, and `_`. - +1. File names should be **machine readable**: avoid spaces, symbols, and special characters. Prefer file names that are all lower case, and never +have names that differ only in their capitalization. Use `.R` as the extension of R files. + ``` # Good fit_models.R utility_functions.R + exploratory-data-analysis.R # Bad fit models.R foo.r - stuff.r + ExploratoryDataAnaylsis.r + ``` + +2. File names should be **human readable**: use file names to describe what's in the file. + + ``` + # good + report-draft-notes.txt + + # bad + temp.r + ``` + + Use the same structure for closely related files: -If files should be run in a particular order, prefix them with numbers. If it -seems likely you'll have more than 10 files, left pad with zero: + ``` + # good + figure-01.png + figure-02.png - 00_download.R - 01_explore.R - ... - 09_model.R - 10_visualize.R + # bad + figure 1.png + fig 02.png + ``` -If you later realise that you've missed some steps, it's tempting to use `02a`, +3. File names should play well with default ordering: start file names with numbers so that alphabetical sorting puts them in the order they get used. + + ``` + # good + 01-load-data.R + 02-exploratory-analysis.R + 03-model-approach-1.R + 04-model-approach-2.R + + # bad + alternative model.R + code for exploratory analysis.r + model_first_try.R + run-first.r + ``` + + If you later realise that you've missed some steps, it's tempting to use `02a`, `02b`, etc. However, I think it's generally better to bite the bullet and rename all files. -Pay attention to capitalization, since you, or some of your collaborators, -might be using an operating system with a case-insensitive file system (e.g., -Microsoft Windows or OS X) which can lead to problems with (case-sensitive) -revision control systems. Prefer file names that are all lower case, and never -have names that differ only in their capitalization. +4. Don't [tempt fate](https://phdcomics.com/comics.php?f=1531) by using "final" or similar words in file names. Instead either rely on Git to track changes over time, opr failing that put the date, formatted as year-month-day, in the file name. + + ``` + # good + report-2022-03-20.qmd + report-2022-04-02.qmd + + # bad + finalreport.qmd + FinalReport-2.qmd + ``` ## Organisation From 08d5d59bfc06fa72108fceb3790c15ebd1e54acb Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Tue, 25 Feb 2025 08:55:25 -0600 Subject: [PATCH 2/3] Change from review --- files.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files.qmd b/files.qmd index 660cdb6..8d35104 100755 --- a/files.qmd +++ b/files.qmd @@ -59,7 +59,7 @@ have names that differ only in their capitalization. Use `.R` as the extension o `02b`, etc. However, I think it's generally better to bite the bullet and rename all files. -4. Don't [tempt fate](https://phdcomics.com/comics.php?f=1531) by using "final" or similar words in file names. Instead either rely on Git to track changes over time, opr failing that put the date, formatted as year-month-day, in the file name. +4. Don't [tempt fate](https://phdcomics.com/comics.php?f=1531) by using "final" or similar words in file names. Instead either rely on Git to track changes over time, or failing that put the date, formatted as year-month-day, in the file name. ``` # good From 999e761a24fdd7e89799026374c019f8ffa1796a Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Fri, 28 Feb 2025 15:50:21 -0600 Subject: [PATCH 3/3] Feedback from code review --- files.qmd | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/files.qmd b/files.qmd index 8d35104..c2993d3 100755 --- a/files.qmd +++ b/files.qmd @@ -3,7 +3,7 @@ ## Names 1. File names should be **machine readable**: avoid spaces, symbols, and special characters. Prefer file names that are all lower case, and never -have names that differ only in their capitalization. Use `.R` as the extension of R files. +have names that differ only in their capitalization. Delimit words with `-` or `_`. Use `.R` as the extension of R files. ``` # Good @@ -31,15 +31,15 @@ have names that differ only in their capitalization. Use `.R` as the extension o ``` # good - figure-01.png - figure-02.png + fig-eda.png + fig-model-3.png # bad - figure 1.png - fig 02.png + figure eda.PNG + fig model three.png ``` -3. File names should play well with default ordering: start file names with numbers so that alphabetical sorting puts them in the order they get used. +3. File names should play well with default ordering. If your file names contain dates, use yyyy-mm-dd (ISO8601) format so they sort in chronological order. If your file names include numbers, make sure to pad them with the appropriate number of zeros so that (e.g.) 11 doesn't get sorted before 2. If files should be used in a specific order, put the number at the start, not the end. ``` # good @@ -47,10 +47,14 @@ have names that differ only in their capitalization. Use `.R` as the extension o 02-exploratory-analysis.R 03-model-approach-1.R 04-model-approach-2.R + 2025-01-01-report.Rmd + 2025-02-01.report.Rmd # bad alternative model.R code for exploratory analysis.r + feb 01 report.Rmd + jan 01 report.Rmd model_first_try.R run-first.r ``` @@ -59,7 +63,7 @@ have names that differ only in their capitalization. Use `.R` as the extension o `02b`, etc. However, I think it's generally better to bite the bullet and rename all files. -4. Don't [tempt fate](https://phdcomics.com/comics.php?f=1531) by using "final" or similar words in file names. Instead either rely on Git to track changes over time, or failing that put the date, formatted as year-month-day, in the file name. +4. Don't [tempt fate](https://phdcomics.com/comics.php?f=1531) by using "final" or similar words in file names. Instead either rely on Git to track changes over time, or failing that, put the date in the file name. ``` # good