r.rmd

---
title: R code
layout: default
output: bookdown::html_chapter
---

# R code {#r}

The first principle of using a package is that all R code goes in `R/`. In this chapter, you'll learn about the `R/` directory, my recommendations for organising your functions into files, and some general tips on good style. You'll also learn about some important differences between functions in scripts and functions in packages.

## R code workflow {#r-workflow}

The first advantage to using a package is that it's easy to re-load your code. You can either run `devtools::load_all()`, or in RStudio press __Cmd + Shift + L__,  which also saves all open files, saving you a keystroke.

These keyboard shortcut leads to a fluid development workflow:

1. Edit an R file.

1. Press Ctrl/Cmd + Shift + L.

1. Explore the code in the console.

1. Rinse and repeat.

Congratulations! You've learned your first package development workflow. Even if you learn nothing else from this book, you'll have gained a useful workflow for editing and reloading R code.

## Organising your functions {#r-organising}

While you're free to arrange functions into files as you wish, the two extremes are bad: don't put all functions into one file and don't put each function into its own separate file. (It's OK if some files only contain one function, particularly if the function is large or has a lot of documentation.). File names should be meaningful and end in `.R`.

```{r, eval = FALSE}
# Good
fit_models.R
utility_functions.R

# Bad
foo.r
stuff.r
```

Pay attention to capitalization, since you, or some of your collaborators, might be using an operating system with a case-insensitive file system (e.g., Microsoft Windows). Avoid problems by never using filenames that differ only in capitalisation.

My rule of thumb is that if I can't remember the name of the file where a function lives, I need to either separate the functions into more files or give the file a better name. (Unfortunately you can't use subdirectories inside `R/`. The next best thing is to use a common prefix, e.g., `abc-*.R`.).

The arrangement of functions within files is less important if you master two important RStudio keyboard shortcuts that let you jump to the definition of a function:

*   Click a function name in code and press __F2__.

*   Press __Ctrl + .__ then start typing the name:

    ```{r, echo = FALSE}
    bookdown::embed_png("screenshots/file-finder.png", dpi = 220)
    ```

After navigating to a function using one of these tools, you can go back to where you were by clicking the back arrow at the top-left of the editor (`r bookdown::embed_png("screenshots/arrows.png", dpi = 240)`), or by pressing Ctrl/Cmd-F9.

## Code style {#style}

Good coding style is like using correct punctuation. You can manage without it, but it sure makes things easier to read. As with styles of punctuation, there are many possible variations. The following guide describes the style that I use (in this book and elsewhere). It is based on Google's [R style guide](https://google-styleguide.googlecode.com/svn/trunk/Rguide.xml), with a few tweaks. 

You don't have to use my style, but I strongly recommend that you use a consistent style and you document it. If you're working on someone elses code, don't impose your own style. Instead, read their style documentation and follow it as closely as possible.

Good style is important because while your code only has one author, it will usually have multiple readers. This is especially true when you're writing code with others. In that case, it's a good idea to agree on a common style up-front. Since no style is strictly better than another, working with others may mean that you'll need to sacrifice some preferred aspects of your style.

The formatR package, by Yihui Xie, makes it easier to clean up poorly formatted code. It can't do everything, but it can quickly get your code from terrible to pretty good. Make sure to read [the notes on the website](http://yihui.name/formatR/) before using it. It's as easy as:

```{r, eval = FALSE}
install.packages("formatR")
formatR::tidy_dir("R")
```

### Object names

Variable and function names should be lowercase. Use an underscore (`_`) to separate words within a name (reserve `.` for S3 methods). Camel case is a legitimate alternative, but be consistent!  Generally, variable names should be nouns and function names should be verbs. Strive for names that are concise and meaningful (this is not easy!).

```{r, eval = FALSE}
# Good
day_one
day_1

# Bad
first_day_of_the_month
DayOne
dayone
djm1
```

Where possible, avoid using names of existing functions and variables. This will cause confusion for the readers of your code.

```{r, eval = FALSE}
# Bad
T <- FALSE
c <- 10
mean <- function(x) sum(x)
```

### Spacing

Place spaces around all infix operators (`=`, `+`, `-`, `<-`, etc.). The same rule applies when using `=` in function calls. Always put a space after a comma, and never before (just like in regular English).

```{r, eval = FALSE}
# Good
average <- mean(feet / 12 + inches, na.rm = TRUE)

# Bad
average<-mean(feet/12+inches,na.rm=TRUE)
```

There's a small exception to this rule: `:`, `::` and `:::` don't need spaces around them. (If you haven't seen `::` or `:::` before, don't worry - you'll learn all about them in [namespaces](#namespace).)

```{r, eval = FALSE}
# Good
x <- 1:10
base::get

# Bad
x <- 1 : 10
base :: get
```

Place a space before left parentheses, except in a function call.

```{r, eval = FALSE}
# Good
if (debug) do(x)
plot(x, y)

# Bad
if(debug)do(x)
plot (x, y)
```

Extra spacing (i.e., more than one space in a row) is ok if it improves alignment of equal signs or assignments (`<-`).

```{r, eval = FALSE}
list(
  total = a + b + c, 
  mean  = (a + b + c) / n
)
```

Do not place spaces around code in parentheses or square brackets (unless there's a comma, in which case see above).

```{r, eval = FALSE}
# Good
if (debug) do(x)
diamonds[5, ]

# Bad
if ( debug ) do(x)  # No spaces around debug
x[1,]   # Needs a space after the comma
x[1 ,]  # Space goes after comma not before
```

### Curly braces

An opening curly brace should never go on its own line and should always be followed by a new line. A closing curly brace should always go on its own line, unless it's followed by `else`.

Always indent the code inside curly braces.

```{r, eval = FALSE}
# Good

if (y < 0 && debug) {
  message("Y is negative")
}

if (y == 0) {
  log(x)
} else {
  y ^ x
}

# Bad

if (y < 0 && debug)
message("Y is negative")

if (y == 0) {
  log(x)
} 
else {
  y ^ x
}
```

It's ok to leave very short statements on the same line:

```{r, eval = FALSE}
if (y < 0 && debug) message("Y is negative")
```

### Line length

Strive to limit your code to 80 characters per line. This fits comfortably on a printed page with a reasonably sized font. If you find yourself running out of room, this is a good indication that you should encapsulate some of the work in a separate function.

### Indentation

When indenting your code, use two spaces. Never use tabs or mix tabs and spaces. Change these options in the code preferences pane:

```{r, echo = FALSE}
bookdown::embed_png("screenshots/style-options.png", dpi = 220)
```

The only exception is if a function definition runs over multiple lines. In that case, indent the second line to where the definition starts:

```{r, eval = FALSE}
long_function_name <- function(a = "a long argument", 
                               b = "another argument",
                               c = "another long argument") {
  # As usual code is indented by two spaces.
}
```

### Assignment

Use `<-`, not `=`, for assignment.

```{r}
# Good
x <- 5
# Bad
x = 5
```

### Commenting guidelines

Comment your code. Each line of a comment should begin with the comment symbol and a single space: `# `. Comments should explain the why, not the what. \index{comments}

Use commented lines of `-` and `=` to break up your file into easily readable chunks.

```{r, eval = FALSE}
# Load data ---------------------------

# Plot data ---------------------------
```

## Differences between functions in scripts and in packages {#r-differences}

Code in a package should not have side effects. Your code should only create objects (mostly functions), and you should not call functions that affect the global state. This means:

* __Don't use `library()` or `require()`__. Use the [DESCRIPTION](description.html) 
  to specify your package's requirements.
  
* __Never use `source()`__ to load code from a file. Rely on 
  `devtools::load_all()` to automatically source all files in `R/`.
  
* __Don't modify global `options()` or graphics `par()`__. Put state changing 
  operations in functions that the user can call when they want.
  
* __Don't save files to disk with `write()`, `write.csv()`, or `saveRDS()`__. 
  Use [data/](data.html) to cache important data files.

There are two reasons to avoid side-effects. The first reason is pragmatic: while functions with side-effects will work while you're developing a package locally with `devtools::load_all()`, they won't work when you're using a package. This is because your R code is only run once when the package is built, and not every time it's loaded. The second reason is principled: you shouldn't change global states behind your users' backs.

### When you __do__ need side-effects

Occasionally, packages do need side-effects. This is most common if your package talks to an external system --- you might need to do some initial setup when the package loads. To do that, you can use two special functions: `.onLoad()` and `.onAttach()`. These are called when the package is loaded and attached. You'll learn about the distinction between the two in [Namespaces](#namespace). For now, you should always use `.onLoad()` unless explicitly directed otherwise.

Some common uses of `.onLoad()` and `.onAttach()` are:

*   To dynamically load a compiled DLL. In most cases, you won't need to 
    use `.onLoad()` to do this. Instead, you'll use a special namespace 
    construct; see [namespaces](#namespace) for details. 

*   To display an informative message when the package loads. This might make 
    usage conditions clear, or display useful tips. Startup messages is one 
    place where you should use `.onAttach()` instead of `.onLoad()`. To display 
    startup messages, always use `packageStartupMessage()`, and not `message()`. 
    (This allows `suppressPackageStartupMessages()` to selectively suppress 
    package startup messages).

    ```{r, eval = FALSE}
    .onAttach <- function(libname, pkgname) {
      packageStartupMessage("Welcome to my package")
    }
    ```
    
*   To connect R to another programming language. For example, if you use rJava
    to talk to a `.jar` file, you need to call `rJava::.jpackage()`. To
    make C++ classes available as reference classes in R with Rcpp modules,
    you call `Rcpp::loadRcppModules()`.

*   To register vignette engines with `tools::vignetteEngine()`.

*   To set custom options for your package with `options()`. To avoid conflicts
    with other packages, ensure that you prefix option names with the name
    of your package. Also be careful not to override options that the user
    has already set.
    
    I use the following code in devtools to set up useful options:
    
    ```{r, eval = FALSE}
    .onLoad <- function(libname, pkgname) {
      op <- options()
      op.devtools <- list(
        devtools.path = "~/R-dev",
        devtools.install.args = "",
        devtools.name = "Your name goes here",
        devtools.desc.author = '"First Last <first.last@example.com> [aut, cre]"',
        devtools.desc.license = "What license is it under?",
        devtools.desc.suggests = NULL,
        devtools.desc = list()
      )
      toset <- !(names(op.devtools) %in% names(op))
      if(any(toset)) options(op.devtools[toset])
    
      invisible()
    }
    ```
    
As you can see in the examples, `.onLoad()` and `.onAttach()` are called with two arguments: `libname` and `pkgname`. They're rarely used (they're a holdover from the days when you needed to use `library.dynam()` to load compiled code). They give the path where the package is installed (the "library"), and the name of the package.

If you use `.onLoad()`, consider using `.onUnload()` to clean up any side effects. By convention, `.onLoad()` and friends are usually saved in a file called `zzz.R`. (Note that `.First.lib()` and `.Last.lib()` are old versions of `.onLoad()` and `.onUnload()` and should no longer be used.)
    
### S4 classes, generics and methods

Another type of side-effect is defining S4 classes, methods and generics. R packages capture these side-effects so they can be replayed when the package is loaded, but they need to be called in the right order. For example, before you can define a method, you must have defined both the generic and the class. This requires that the R files be sourced in a specific order. This order is controlled by the `Collate` field in the `DESCRIPTION`. This is described in more detail in [documenting S4](#man-s4).

## CRAN notes {#r-cran}

(Each chapter will finish with some hints for submitting your package to CRAN. If you don't plan on submitting your package to CRAN, feel free to ignore them!)

If you're planning on submitting your package to CRAN, you must use only ASCII characters in your `.R` files. You can still include unicode characters in strings, but you need to use the special unicode escape `"\u1234"` format. The easiest way to do that is to use `stringi::stri_escape_unicode()`:

```{r}
x <- "This is a bullet •"
y <- "This is a bullet \u2022"
identical(x, y)

cat(stringi::stri_escape_unicode(x))
```

Your R directory should not include any files other than R code. Subdirectories will be silently ignored.