forked from tidyverse/style
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathfiles.qmd
executable file
·96 lines (72 loc) · 2.75 KB
/
files.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
# Files {#sec-files}
## 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. Delimit words with `-` or `_`. 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
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:
```
# good
fig-eda.png
fig-model-3.png
# bad
figure eda.PNG
fig model three.png
```
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
01-load-data.R
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
```
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.
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
report-2022-03-20.qmd
report-2022-04-02.qmd
# bad
finalreport.qmd
FinalReport-2.qmd
```
## Organisation
It's hard to describe exactly how you should organise your code across multiple files. I think the best rule of thumb is that if you can give a file a concise name that still evokes its contents, you've arrived at a good organisation. But getting to that point is hard.
## Internal structure
Use commented lines of `-` and `=` to break up your file into easily readable
chunks.
```{r}
# Load data ---------------------------
# Plot data ---------------------------
```
If your script uses add-on packages, load them all at once at the very
beginning of the file. This is more transparent than sprinkling `library()`
calls throughout your code or having hidden dependencies that are loaded in a
startup file, such as `.Rprofile`.