From 03ee88bb75b2d09eec042cdc27dc10abac18a5ac Mon Sep 17 00:00:00 2001 From: njlyon0 Date: Tue, 17 Sep 2024 14:51:00 -0700 Subject: [PATCH] feat: generalized 'script vs. notebook' page to be more coding language-agnostic --- tip_notebook-vs-script.qmd | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/tip_notebook-vs-script.qmd b/tip_notebook-vs-script.qmd index ede28b4..231ae93 100644 --- a/tip_notebook-vs-script.qmd +++ b/tip_notebook-vs-script.qmd @@ -2,31 +2,39 @@ title: "Notebooks versus Scripts" --- -When coding in R, either R scripts (.R files) or R markdowns (.Rmd files) are viable options but they have different advantages and disadvantages that we will cover below. +When writing code, either scripts (e.g., `.R`, `.py`, `.sh`, etc.) or notebook files (e.g., `.Rmd`, `.ipynb`, `.qmd`, etc.) can be viable options but they have different advantages and disadvantages that we will cover below. -## R Scripts +## Scripts -### Positives +:::{.panel-tabset} -R scripts' greatest strength is their flexibility. They allow you to format a file in whatever way is most intuitive to you. Additionally, R scripts can be cleaner for `for` loops insofar as they need not be concerned with staying within a given code chunk (as would be the case for a .Rmd). Developing a new workflow can be swiftly accomplished in an R script as some or all of the code in a script can be run by simply selecting the desired lines rather than manually running the desired chunks in a .Rmd file. Finally, R scripts can also be a better home for custom functions that can be `source`d by another file (even a .Rmd!) for making repeated operations simpler to read. +### Strengths + +**The greatest strength of scripts is their flexibility**. They allow you to format a file in whatever way is most intuitive to you. Additionally, scripts can be cleaner for iterative operations (i.e., `for` loops) insofar as they need not be concerned with staying within a given code chunk (as would be the case for a notebook file). Developing a new workflow can be swiftly accomplished in a script as some or all of the code in a script can be run by simply selecting the desired lines rather than manually running the desired chunks in a .Rmd file. Finally, scripts can also be a better home for custom functions that can be `source`d by another file (even by a notebook!) for making repeated operations simpler to read. ### Potential Weaknesses -The benefit of extreme flexibility in R scripts can sometimes be a disadvantage however. We've all seen (and written) R scripts that have few or no comments or where lines of code are densely packed without spacing or blank lines to help someone new to the code understand what is being done. R scripts can certainly be written in a way that is accessible to those without prior knowledge of what the script accomplishes but they do not *enforce* such structure. This can make it easy, especially when we're feeling pressed for time, to exclude structure that helps our code remain reproducible and understandable. +The benefit of extreme flexibility in scripts can sometimes be a disadvantage however. We've all seen (and written) scripts that have few or no comments or where lines of code are densely packed without spacing or blank lines to help someone new to the code understand what is being done. Scripts can certainly be written in a way that is accessible to those without prior knowledge of what the script accomplishes but they do not _enforce_ such structure. This can make it easy--especially when we're feeling pressed for time--to exclude structure that helps our code remain reproducible and understandable. + +::: -## R Markdowns +## Notebooks -### Positives +:::{.panel-tabset} -R markdown files' ability to "knit" as HTML or PDF documents makes them extremely useful in creating outward-facing reports. This is particularly the case when the specific code is less important to communicate than visualizations and/or analyses of the data but .Rmd files do facilitate `echo`ing the code so that report readers can see how background operations were accomplished. The code chunk structure of these files can also nudge users towards including valuable comments (both between chunks and within them) though of course .Rmd files do not enforce such non-code content. +### Strengths + +Notebook files' ability to "knit" or "rendered" as HTML or PDF documents makes them **extremely useful in creating outward-facing reports**. This is particularly the case when the specific code is less important to communicate than visualizations and/or analyses of the data but notebook files do facilitate `echo`ing the code so that report readers can see how background operations were accomplished. The code chunk structure of these files can also nudge users towards including valuable comments (both between chunks and within them) though of course notebook files do not enforce such non-code content. ### Potential Weaknesses -R markdowns can fail to knit due to issues even when the code within the chunks works as desired. Duplicate code chunk names or a failure to install LaTeX can be a frustrating hurdle to overcome between functioning code and a knit output file. When code must be re-run repeatedly (as is often the case when developing a new workflow) the stop-and-start nature of running each code chunk separately can also be a small irritation. +Notebook files can fail to knit/render due to issues even when the code within the chunks works as desired. Duplicate code chunk names or a failure to install LaTeX (or related support software) can be a frustrating hurdle to overcome between functioning code and a rendered output file. When code must be re-run repeatedly (as is often the case when developing a new workflow) the stop-and-start nature of running each code chunk separately can also be a small irritation. + +::: -## Script vs. Markdown Summary +## Script vs. Notebook Summary -Taken together, both R scripts and R markdown files can empower users to write reproducible, transparent code. However, both file types have some key limitations that should be taken into consideration when choosing which to use as you set out to create a new code product. +Taken together, **both scripts and notebooks can empower users to write reproducible, transparent code**. However, both file types have some key limitations that should be taken into consideration when choosing which to use as you set out to create a new code product.

Photo of people walking sampling insects at a farm where a wildflower strip has been planted between two row-cropped areas