A few notes

[ashiklom]

Just a few comments, while they're fresh on my mind after this tutorial was run. At some point, I can open a PR with the revisions indicated here.

• Style guides

  • One thing I might consider adding is that style guides are not style rules. Many style guides will specifically say that if violating one of their guidelines makes your code clearer or easier to work with, do it.
  • It might also be worth mentioning that many text editors can be configured to yell at you when your code breaks style rules (i.e. code "linters"; e.g. RStudio's "code diagnostics"), and that it's a good idea to have these on.

• Comments

  • Another way to say "document design and purpose, not mechanics" is "document why, not how".
  • I might also mention that an incorrect/outdated comment is often worse than no comment at all.
  • Under documentation generators, I would add roxygen2 to the list, since it's probably the one we use the most.

• Modularity / Don't repeat yourself

  • In general, this is a good principle...but I've increasingly come around to the view that abstraction comes at a cost, and, similarly, that the wrong abstraction can be more costly than duplication. Here are two more posts that provide nice discussions of this, and both of them come together on the idea that it's a good idea to duplicate code several times to identify how best to abstract (i.e. modularize) it (e.g. which variables will change, what is the range of functionality you expect it to support, etc.).
  • That said, I definitely think the general concept of DRY is very important, so that's still an important message to convey. My comments are more nuance than anything else.

• Loops

  • As I mentioned in the discussion, loops in R are not inherently slow, and more generally, are not inherently bad. Regarding slowness, note that in the following example, apply is slower than a loop, especially if you pre-allocate memory for the output. But all the options pale in comparison, and in terms of clarity, with base R's colMeans function:

n <- 2500
data <- matrix(rnorm(n^2), n, n)

loop <- function(x) {
  # Create a blank object, but don't pre-allocate
  result <- numeric()
  for (col in seq_len(ncol(x))) {
    result <- c(result, mean(x[, col]))
  }
  result
}

loop2 <- function(x) {
  # Pre-allocate memory
  result <- numeric(n)
  for (col in seq_len(ncol(x))) {
    result[col] <- mean(x[, col])
  }
  result
}

microbenchmark::microbenchmark(
  loop = loop(data),
  loop2 = loop2(data),
  apply = apply(data, 2, mean),
  colMeans = colMeans(data)
)
#> Unit: milliseconds
#>      expr       min        lq      mean    median        uq       max
#>      loop 40.100811 43.093317 46.842495 46.797980 47.979631  91.96781
#>     loop2 33.794390 35.292669 38.227707 36.128164 37.599016  78.73944
#>     apply 53.358353 77.231662 79.053773 78.281253 80.420645 161.34888
#>  colMeans  4.413732  4.550543  5.251516  4.653667  4.807175  17.61293
#>  neval
#>    100
#>    100
#>    100
#>    100

• I like the way loops vs. functionals (e.g. lapply, purrr::map, etc.) are framed in the Iteration chapter of R for Data Science. The general argument is that functionals may be preferable to loops when they are less verbose and more clear by removing all the loop boilerplate and emphasizing the things that are changing (what you're looping over, and what you're doing in each loop).
• It may be worth pointing out several advantages of loops, and places they cannot be replaced:
  • Loops lend themselves well to tracking progress (e.g. via progress bars), and, similarly, to not losing all your work if only one iteration fails. You can accomplish both of these with functionals, especially with the help of the purrr package, but it's not necessarily obvious.
  • More importantly, loops are essential for doing dynamic simulations where the current state depends on previous states (e.g. x[i] depends on x[i-1]).
• Another important disadvantage of loops in most languages is that they are sensitive to the environment around them. For instance, code like for (i in seq_len(length(x)) result <- c(result, x[i]) depends on what the starting value of result is outside the loop. If you forget to re-set result, you could end up with result that is several times longer than what you need!

• Another concept: "Return early" / "The happy path is along the left"
  • The basic idea is to try to minimize the control flow complexity of a function. One of the best tools for this is the idea of early returns. For instance, this:

f <- function(x) {
  if (!is.numeric(x)) {
    warning("X must be numeric")
    result <- NA
  } else {
    a <- x + 3
    b <- x^2 + 2
    result <- x + a + b
  }
  result
}

...may be better written with an early return, like this:

f <- function(x) {
  if (!is.numeric(x)) {
    warning("X must be numeric")
    return(NA)
  }
  a <- x + 3
  b <- x^2 + 2
  x + a + b
}

• One way to think of this is to try to look for ways to avoid else statements in if clauses.

[bpbond]

Some thoughts re the loops section:

I really liked @pralitp 's framing of "know and use language-specific powers/features" or something like that. So, loops in R aren't always bad, but be darn sure you know about the *apply functions; you don't need to template/polymorph everything but if writing in C++ be aware of their power and pitfalls. Et cetera. Anyway, I do like that as an alternative and more positive way to frame that section.