Clarify a few bits of functions

functions.Rmd

@@ -282,7 +282,7 @@ When you run a pipe interactively, it's easy to see if something goes wrong. Whe
 
 ## Functions
 
-One of the best ways to grow in your capabilities as a user of R for data science is to write functions. Functions allow you to automate common tasks, instead of using copy-and-paste. Writing good functions is a lifetime journey: you won't learn everything but you'll hopefully get to start walking in the right direction.
+One of the best ways to grow in your skills as a data scientist in R is to write functions. Functions allow you to automate common tasks, instead of using copy-and-paste. Writing good functions is a lifetime journey: you won't learn everything but you'll hopefully get to start walking in the right direction.
 
 Whenever you've copied and pasted code more than twice, you need to take a look at it and see if you can extract out the common components and make a function. For example, take a look at this code. What does it do?
 
@@ -313,7 +313,9 @@ To write a function you need to first analyse the operation. How many inputs doe
   (max(df$a, na.rm = TRUE) - min(df$a, na.rm = TRUE))
 ```
 
-It's often a good idea to rewrite the code using some temporary values. Here this function only takes one input, so I'll call it `x`:
+This code only has one input: `df$a`.
+
+To make that more clear, it's a good idea to rewrite the code using some temporary variables. Here this function only takes one input, so I'll call it `x`:
 
 ```{r}
 x <- 1:10
@@ -327,7 +329,7 @@ rng <- range(x, na.rm = TRUE)
 (x - rng[1]) / (rng[2] - rng[1])
 ```
 
-Now that I've simplified the code, and made sure it works, I can turn it into a function:
+Now that I've simplified the code, and checked that it still works, I can turn it into a function:
 
 ```{r}
 rescale01 <- function(x) {
@@ -461,9 +463,7 @@ y <- 10
 x <- if (y < 20) "Too low" else "Too high"
 ```
 
-You can explicitly return early from a function with `return()`. I think it's best to save the use of `return()` to signal when you're returning early for some special reason.
-
-It's sometimes useful when you want to write code like this:
+You can explicitly return early from a function with `return()`. I think it's best to save the use of `return()` to signal that you can return early with a simpler solution. For example, you might write an if statement like this:
 
 ```{r, eval = FALSE}
 f <- function() {
@@ -482,7 +482,7 @@ f <- function() {
 }
 ```
 
-Because you can rewrite it as:
+But if the first block is very long, by the time you get to the else, you've forgotten what's going on. One way to rewrite it is to use an early return for the simple case:
 
 ```{r, eval = FALSE}
 
@@ -502,6 +502,10 @@ f <- function() {
 }
 ```
 
+This tends to make the code easier to understand, because you don't need quite so much context to understand it.
+
+#### Invisible values
+
 Some functions return "invisible" values. These are not printed out by default but can be saved to a variable:
 
 ```{r}