Minor workflow polishing

workflow-basics.Rmd

@@ -72,8 +72,7 @@ some.people.use.periods
 And_aFew.People_RENOUNCEconvention
 ```
 
-We'll come back to code style later, in Chapter \@ref(functions) on functions.
-If you're interested in learning more about about best practices for code style, I also recommend The tidyverse style guide: [https://style.tidyverse.org](https://style.tidyverse.org/).
+We'll come back to names again when we talk more about code style in Chapter \@ref(workflow-style).
 
 You can inspect an object by typing its name:
 

workflow-style.Rmd

@@ -35,27 +35,28 @@ library(nycflights13)
 
 ## Names
 
-Variable names (those created by `<-` and those created by `mutate()`) should use only lowercase letters, numbers, and `_`.
-Use underscores (`_`) to separate words within a name.
+We talked briefly about names in Section \@ref(whats-in-a-name).
+Remember that variable names (those created by `<-` and those created by `mutate()`) should use only lowercase letters, numbers, and `_`.
+Use `_` to separate words within a name.
 
 ```{r, eval = FALSE}
 # Strive for:
 short_flights <- flights |> filter(air_time < 60)
 
 # Avoid:
-
+SHORTFLIGHTS  <- flights |> filter(air_time < 60)
 ```
 
 As a general rule of thumb, it's better to prefer long, descriptive names that are easy to understand, rather than concise names that are fast to type.
 Short names save relatively little time when writing code (especially since autocomplete will help you finish typing them), but can be expensive when you come back to old need and need to puzzle out what a cryptic abbreviation means.
 
-Strive for consistency with your names.
-
-Prefixes are generally better than suffixes because of autocomplete.
+If you have a bunch of names for related things, do your best to be consistent.
+It's easy for inconsistencies to arise when you forget a previous convention, so don't feel bad if you have to go back and rename things.
+If you have a bunch of variables that are some variation on a theme you're generally better off giving them a common prefix, rather than a common suffix, because autocomplete works best on the start of a variable.
 
 ## Spaces
 
-Put spaces on either side of mathematical operators apart from `^` (e.g `+`, `-`, `==`, `<`), and around the assignment operator (`<-`).
+Put spaces on either side of mathematical operators apart from `^` (`+`, `-`, `==`, `<`, ...), and around the assignment operator (`<-`).
 Don't put spaces inside or outside parentheses for regular function calls.
 Always put a space after a comma, just like in regular English.
 
@@ -71,7 +72,6 @@ mean (x ,na.rm=TRUE)
 
 It's OK to add extra spaces if it improves alignment.
 For example, if you're creating multiple variables in `mutate()`, you might want to add spaces so that all the `=` line up.
-This is particularly useful in `case_when()` as it makes it easier to skim the conditions and the values.
 
 ```{r, eval = FALSE}
 flights |> 
@@ -84,11 +84,13 @@ flights |>
 
 ## Pipes
 
-`|>` should always have a space before it and should always be followed by a new line or space (usually a new line).
-After the first step, each line should be indented by two spaces.
+`|>` should always have a space before it and should typically be followed by a newline.
+If the function has named arguments (like `mutate()` or `summarise()`), always put each argument on a new line.
+If the function doesn't have named arguments (like `select()` or `filter()` keep everything on one line unless it doesn't fit, in which case you should put each argument on its own line.
 
-If the function has named arguments (like `mutate()` or `summarise()`) then put each argument on a new line, indented by another two spaces.
-Make sure the closing parentheses start a new line and are lined up with the start of the function name.
+After the first step of the pipeline, indent each line by two spaces.
+If you're putting arguments on their own line, indent each argument by an extra two spaces.
+Make sure `)` is on its own line, and un-indented to match the horizontal position of the function name.
 
 ```{r, eval = FALSE}
 # Strive for 
@@ -106,17 +108,16 @@ flights|> filter(!is.na(arr_delay), !is.na(tailnum)) |>
                                  n = n())
 ```
 
-This structure makes it easier to add new steps (or rearrange existing steps), modify elements within a step, and to get a 50,000 view just by skimming the left-hand side.
-
-It's OK to shirk some of these rules if your snippet fits easily on one line.
-But in our experience, it's pretty common for short snippets to grow longer, so you'll usually save time in the long run by starting with all the vertical space you need.
+This structure makes it easier to add new steps, rearrange existing steps, modify elements within a step, and to get a 50,000 view by skimming the left-hand side.
+It's OK to shirk some of these rules if your pipeline fits easily on one line.
+But it's common for short snippets to grow longer, so you'll usually save time in the long run by starting with all the vertical space you need.
 
 ```{r, eval = FALSE}
 # This fits compactly on one line
 df |> mutate(y = x + 1)
 
-# While this spacing feels breezy, it's easily extended to 
-# more variables and more steps
+# While this takes up 4x as many lines, it's easily extended to 
+# more variables and more steps in the future
 df |> 
   mutate(
     y = x + 1
@@ -136,7 +137,7 @@ flights |>
   geom_line()
 ```
 
-If you can fit all of the arguments on to a single line, put each argument on its own line.
+Again, if you can fit all of the arguments to a function on to a single line, put each argument on its own line:
 
 ```{r, eval = FALSE}
 flights |> 
@@ -189,3 +190,13 @@ RStudio provides a keyboard shortcut to create these headers (Cmd/Ctrl + Shift +
 #|   bottom-left of the script editor.
 knitr::include_graphics("screenshots/rstudio-nav.png")
 ```
+
+## Exercises
+
+1.  Restyle each of the following pipelines following the guidelines above.
+
+    ```{r, eval = FALSE}
+    flights|>filter(dest=="IAH")|>group_by(year,month,day)|>summarise(n=n(),delay=mean(arr_delay,na.rm=TRUE))|>filter(n>10)
+
+
+    ```