Project structure

# >    🏗 >    Project structure
### Danielle Navarro

---

layout: true
 
<div class="my-footer">

 <a href="https://slides.djnavarro.net/project-structure" target="_blank">slides.djnavarro.net/project-structure</a>

</div>

---

## What are we going to cover?

- Naming files
- Project structure

---

## What is the assumed knowledge?

- This is an introductory unit
- Contains almost no programming content at all

---

## Where can I find the resources?

- These slides: [slides.djnavarro.net/project-structure](https://slides.djnavarro.net/project-structure)
- YouTube videos: [youtube.djnavarro.net/project-structure](https://youtube.djnavarro.net/project-structure)

---

background-image: url("img/free-to-use-sounds-xbHgspX4_nc-unsplash.jpg")
background-size: cover

.pull-left-narrow[
 .huge-primary[.plainwhite[1]]
]
.pull-right-wide[
 
.larger[.embolden[.plainwhite[Naming things]]]
]

---

- "Everything I know is from Jenny Bryan"
- This section is based on (i.e., shamelessly mimics) her slides
- https://speakerdeck.com/jennybc/how-to-name-files

---

.hand[
’Tis but thy name that is my enemy; 
Thou art thyself, though not a Montague. 
What’s Montague? It is nor hand, nor foot, 
Nor arm, nor face, nor any other part 
Belonging to a man. O, be some other name! 
What’s in a name? That which we call a rose 
By any other name would smell as sweet; 
So Romeo would, were he not Romeo call’d, 
Retain that dear perfection which he owes 
Without that title. Romeo, doff thy name; 
And for thy name, which is no part of thee, 
Take all myself.
]

---

---

- `reading01_shakespeare_romeo-and-juliet_act01.docx`
- `reading01_shakespeare_romeo-and-juliet_act02.docx`
- `reading01_shakespeare_romeo-and-juliet_act03.docx`
- `reading02_shakespeare_othello.docx`
- `reading19_plath_the-bell-jar.docx`

- `Romeo and Juliet Act 1.docx`
- `Romeo and juliet act 2.docx`
- `Shakespeare RJ act3.docx`
- `shakespeare othello I think?.docx`
- `belljar plath (1).docx`

---

- Be nice to machines
- Be nice to humans
- Make sorting and searching easy

---

background-image: url("img/free-to-use-sounds-xbHgspX4_nc-unsplash.jpg")
background-size: cover

.pull-left-narrow[
 .huge-primary[.plainwhite[2]]
]
.pull-right-wide[
 
.larger[.embolden[.plainwhite[Names machines like]]]
]

---

- Machines sometimes get confused by spaces
- Easier to write code when files don't have spaces

- ✅ `romeo-and-juliet_act01.docx`
- ✅ `midsummer-nights-dream.docx`

- ❌ `romeo and juliet act 1.docx`
- ❌ `midsummer nights dream.docx`

---

- Machines sometimes get confused by special characters
- Some characters have special meaning, e.g., `^.*?+|$`
- If you can, avoid accents `ñ` (but consider accessibility!)

- ✅ `what-the-cat.docx`
- ✅ `essay_romeo-and-juliet_draft01.docx`

- ❌ `what-the-cat?.docx`
- ❌ `essay "romeo and juliet" draft01.docx`
- ❌ `essay "romeo and juliet" draft01(1).docx`

---

- Some operating systems treat `a` and `A` the same
- Some operating systems treat `a` and `A` differently
- Never have two files that differ only in case
- Be consistent

- ✅ `othello.docx`
- ✅ `romeo-and-juliet.docx`

- ❌ `othello.docx`
- ❌ `Othello.docx`
- ❌ `Romeo-and-juliet.docx`

---

- Use hyphen `-` to mean "different words that are part of the same chunk"
- Use underscore `_` to separate different chunks

- Chunk: [identifier] `reading01`, `reading02`, etc
- Chunk: [author] `shakespeare`, `plath`, etc
- Chunk: [title] `othello`, `the-bell-jar`, etc
- Chunk: [section] `act01`, `act02`, etc

- Order: [identifier] [author] [title] [section(optional)]
- ✅ `reading01_shakespeare_romeo-and-juliet_act01.docx`
- ✅ `reading01_shakespeare_romeo-and-juliet_act02.docx`
- ✅ `reading02_shakespeare_othello.docx`
- ✅ `reading19_plath_the-bell-jar.docx`

---

background-image: url("img/free-to-use-sounds-xbHgspX4_nc-unsplash.jpg")
background-size: cover

.pull-left-narrow[
 .huge-primary[.plainwhite[3]]
]
.pull-right-wide[
 
.larger[.embolden[.plainwhite[Names humans like]]]
]

---

- `01.R`
- `02.R`
- `notes.txt`
- `2b.R`
- `notes.docx`

- `analysis01_descriptive-statistics.R`
- `analysis02_preregistered-analysis.R`
- `notes01_realising-the-problem.txt`
- `analysis03_departing-from-the-plan.R`
- `notes02_tentative-write-up.docx`

---

<code class ='r hljs remark-code'>"analysis01_descriptive-statistics.R" "analysis02_preregistered-analysis.R" "notes01_realising-the-problem.txt" "analysis03_departing-from-the-plan.R" "notes02_tentative-write-up.docx"</code>

- Concise, meaningful description
- Usually appended to the end

---

background-image: url("img/free-to-use-sounds-xbHgspX4_nc-unsplash.jpg")
background-size: cover

.pull-left-narrow[
 .huge-primary[.plainwhite[4]]
]
.pull-right-wide[
 
.larger[.embolden[.plainwhite[Easy sort and search]]]
]

---

.hand[File names sometimes need to include dates ... but these dates don't sort in chronological order 😭]

- `1-April-2012.R`
- `1-Jan-2009.R`
- `1-Jan-2012.R`
- `12-Jan-2012.R`
- `2-Jan-2012.R`
- `31-Dec-2009.R`

---

- `2009-01-01.R`
- `2009-12-01.R`
- `2012-01-01.R`
- `2012-01-02.R`
- `2012-04-01.R`

- Dates should follow the `YYYY-MM-DD` format
- Known as the ISO 8601 standard

---

<code class ='r hljs remark-code'>"2009-01-01_original-analysis.R" "2009-12-01_minor-changes-to-original.R" "2012-01-01_analysis-at-2-year-follow-up.R" "2012-01-02_minor-changes-to-follow-up.R" "2012-04-01_combined-original-and-follow-up.R"</code>

---

<code class ='r hljs remark-code'>"2009-01-01_original-analysis.R" "2009-12-01_minor-changes-to-original.R" "2012-01-01_analysis-at-2-year-follow-up.R" "2012-01-02_minor-changes-to-follow-up.R" "2012-04-01_combined-original-and-follow-up.R"</code>

---

- `01_preface.docx`
- `02_introduction.docx`
- `03_method.docx`
- etc...

- `19_appendix-09.docx`
- `20_appendix-10.docx`
- `21_appendix-11.docx`

- Left pad with `0` so that all numbers have same length
- Numbers are more robust than letters (alphabetical order varies)

---

- <code>reading19_plath_the-bell-jar.docx</code>
- <code>notes19_plath_the-bell-jar.docx</code>

---

- <code>notes02_shakespeare_othello.docx</code>
- <code>notes19_plath_the-bell-jar.docx</code>

---

background-image: url("img/manuel-santolaria-ls2vGs4sLCU-unsplash.jpg")
background-size: cover

.pull-left-narrow[
 .huge-secondary[5]
]
.pull-right-wide[
 
.larger[.embolden[.secondary[Project structure]]]
]

---

- Understand file paths
- Use project templates
- Use README files

---

background-image: url("img/manuel-santolaria-ls2vGs4sLCU-unsplash.jpg")
background-size: cover

.pull-left-narrow[
 .huge-secondary[6]
]
.pull-right-wide[
 
.larger[.embolden[.secondary[File paths]]]
]

---

---

- 📂 <code>.plainwhite[project]</code>
 - 📄 <code>.plainwhite[01_initial-plan.docx]</code>
 - 📄 <code>.plainwhite[02_data-collection.R]</code>
 - 📄 <code>.plainwhite[03_initial-analysis.R]</code>

- <code>.plainwhite[project/01_initial-plan.docx]</code>
- <code>.plainwhite[project/02_data-collection.R]</code>
- <code>.plainwhite[project/03_initial-analysis.R]</code>

---

- <code>.plainwhite[project\\01_initial-plan.docx]</code>
- <code>.plainwhite[project\\02_data-collection.R]</code>
- <code>.plainwhite[project\\03_initial-analysis.R]</code>

---

- 📂 <code>.plainwhite[project]</code>
 - 📄 <code>.plainwhite[overview.docx]</code>
 - 📂 <code>.plainwhite[data]</code>
 - 📄 <code>data_ex01.csv</code>
 - 📄 <code>data_ex02.csv</code>
 - 📂 <code>.plainwhite[analysis]</code>
 - 📄 <code>ex01_01_descriptive-statistics.R</code>
 - 📄 <code>ex01_02_inferential-statistics.R</code>
 - 📄 <code>ex02_01_descriptive-statistics.R</code>
 - 📄 <code>ex02_02_inferential-statistics.R</code>
 - 📂 <code>.plainwhite[report]</code>
 - 📄 <code>2021-03-11_report_getting-started.docx</code>

---

- <code>.plainwhite[project/overview.docx]</code>
- <code>project/data/data_ex01.csv</code>
- <code>project/data/data_ex02.csv</code>
- <code>project/analysis/ex01_01_descriptive-statistics.R</code>
- <code>project/analysis/ex01_02_inferential-statistics.R</code>
- <code>project/analysis/ex02_01_descriptive-statistics.R</code>
- <code>project/analysis/ex02_02_inferential-statistics.R</code>
- <code>project/report/2021-03-11_report_getting-started.docx</code>

---

```r
list.files(recursive = TRUE)
```

```
##  [1] "example-template.zip"                           
##  [2] "header.html"                                    
##  [3] "img/free-to-use-sounds-xbHgspX4_nc-unsplash.jpg"
##  [4] "img/jessica-lee-o5GGlwHfff8-unsplash.jpg"       
##  [5] "img/manuel-santolaria-ls2vGs4sLCU-unsplash.jpg" 
##  [6] "img/stil-wtqe5nd5MYk-unsplash.jpg"              
##  [7] "img/twitter-image.png"                          
##  [8] "img/vu-anh-ThyBKNya1yY-unsplash.jpg"            
##  [9] "img/wesley-tingey-snNHKZ-mGfE-unsplash.jpg"     
## [10] "index.html"                                     
## [11] "index.Rmd"                                      
## [12] "libs/font-awesome/css/all.css"                  
## [13] "libs/font-awesome/css/v4-shims.css"             
## [14] "libs/font-awesome/webfonts/fa-brands-400.eot"   
## [15] "libs/font-awesome/webfonts/fa-brands-400.svg"
```

```
## ...the real output is over 15000 files!
```
]

---

```r
list.files(pattern = "unsplash", recursive = TRUE)
```

```
## [1] "img/free-to-use-sounds-xbHgspX4_nc-unsplash.jpg"
## [2] "img/jessica-lee-o5GGlwHfff8-unsplash.jpg"       
## [3] "img/manuel-santolaria-ls2vGs4sLCU-unsplash.jpg" 
## [4] "img/stil-wtqe5nd5MYk-unsplash.jpg"              
## [5] "img/vu-anh-ThyBKNya1yY-unsplash.jpg"            
## [6] "img/wesley-tingey-snNHKZ-mGfE-unsplash.jpg"
```
]

---

background-image: url("img/manuel-santolaria-ls2vGs4sLCU-unsplash.jpg")
background-size: cover

.pull-left-narrow[
 .huge-secondary[7]
]
.pull-right-wide[
 
.larger[.embolden[.secondary[Templating]]]
]

---

- Folder structure already exists
- Starter files already included
- Instructions are already included

- Make a copy of the template
- Rename files as needed
- Start work!

---

background-image: url("img/stil-wtqe5nd5MYk-unsplash.jpg")
background-size: cover

.pull-left-narrow[
 .huge-secondary[8]
]
.pull-right-wide[
 
.larger[.embolden[.secondary[README]]]
]

---

- Most folders should have a <code>.plainwhite[README.txt]</code> or <code>.plainwhite[README.md]</code> file
- Simple text file explaining what's in the folder and what it's for

- In the finished project the README files help your users navigate
- In your project template the README files contain instructions to you!

---

---

## The example template we just made

https://slides.djnavarro.net/project-structure/example-template.zip

## A more realistic template I use sometimes

https://github.com/djnavarro/newproject/

---

background-image: url("img/vu-anh-ThyBKNya1yY-unsplash.jpg")
background-size: cover

.pull-left-narrow[
 .huge-secondary[9]
]
.pull-right-wide[
 
.larger[.embolden[.secondary[Where do projects live?]]]
]

---

- Every user has a "home" folder
 - On windows it might be <code>.plainwhite[C:\Users\danielle]</code>
 - On a mac it might be <code>.plainwhite[/Users/danielle]</code>
 - On ubuntu it might be <code>.plainwhite[/home/danielle]</code>

- User files and folders are inside the user folder
 - The Desktop is usually <code>.plainwhite[danielle/Desktop]</code>
 - The Downloads folder is usually <code>.plainwhite[danielle/Downloads]</code>
 - If you use Dropbox it is usually <code>.plainwhite[danielle/Dropbox]</code>

---

---

.pull-left[
![](https://media.giphy.com/media/3o6fIX5mC1mSgNU0BW/giphy.gif)
]
.pull-right[
- ❌ The Desktop
- ❌ The Downloads folder
- ❌ Stored with non-projects
- ❌ Places that aren't backed up
]

---

- ✅ <code>.plainwhite[C:\Users\danielle\OneDrive\projects]</code>
- ✅ <code>.plainwhite[/Users/danielle/Dropbox/projects]</code>
- ✅ <code>.plainwhite[/home/danielle/Dropbox/projects]</code>

- 📝 this is a folder on your computer that is automatically synchronised
- ✅ Dropbox/OneDrive/etc app ensures your files are the same everywhere
- ✅ the service is designed to be user friendly
- ❌ you don't get to go "back in time" very far

---

.pull-left[
![](https://media.giphy.com/media/efU9WbFkGP9NAkLOWn/giphy.gif)
]
--
.pull-right[
- You've made a huge mistake and need to revert
- You want to check the order you did things
]

---

.pull-left[
![](https://media.giphy.com/media/efU9WbFkGP9NAkLOWn/giphy.gif)
]
.pull-right[
- Special app (e.g., Time Machine)
- Employer backup to server
- Version control with git/GitHub
]

---

.pull-left[
- 📂 <code>.plainwhite[danielle]</code>
 - 📁 <code>.plainwhite[Dropbox]</code>
 - 📁 <code>.plainwhite[GitHub]</code>
]

.pull-right[
- My workflow is different for GitHub versus Dropbox
- So I keep these two separated from the start
]

---

.pull-left[
- 📂 <code>danielle</code>
 - 📂 <code>Dropbox</code>
 - 📂 <code>Work</code>
 - 📁 <code>administration</code>
 - 📁 <code>archives</code>
 - 📁 <code>cheatsheets</code>
 - 📁 <code>projects</code>
 - 📁 <code>teaching</code>
 - 📁 <code>GitHub</code>
]

.pull-right[
- Note the archives folder! 
- Completed  content is not deleted
- It is zipped and moved to archives
- My archives go back to 1998
- Yes I am old 😭
]

---

.pull-left[
- 📂 <code>danielle</code>
 - 📁 <code>Dropbox</code>
 - 📂 <code>GitHub</code>
 - 📁 <code>archive</code>
 - 📁 <code>artwork</code>
 - 📁 <code>other</code>
 - 📁 <code>projects</code>
 - 📁 <code>sites</code>
 - 📁 <code>slides</code>
 - 📁 <code>teaching</code>
]

.pull-right[
- Similar organisation, not the same
- Yours might be different too!
- Key principle: *think* about it 🤔 
]

---

- A project should not "care" where it lives
- Suppose my project folder is <code>floof</code>
- It currently lives at <code>/home/danielle/Dropbox/floof</code>

- ... I move it to <code>/home/danielle/GitHub/floof</code>?
- ... I copy it onto a different computer?
- ... the new computer runs a different operating system?

---

background-image: url("img/jessica-lee-o5GGlwHfff8-unsplash.jpg")
background-size: cover