syntax.qmd

# Syntax

## Object names

> "There are only two hard things in Computer Science: cache invalidation and 
> naming things." 
>
> --- Phil Karlton

Variable and function names should use only lowercase letters, numbers, and `_`. 
Use underscores (`_`) (so called snake case) to separate words within a name. 

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

# Bad
DayOne
dayone
```

Base R uses dots in function names (`contrib.url()`) and class names 
(`data.frame`), but it's better to reserve dots exclusively for the S3 object 
system. In S3, methods are given the name `function.class`; if you also use 
`.` in function and class names, you end up with confusing methods like
`as.data.frame.data.frame()`.

If you find yourself attempting to cram data into variable names (e.g. `model_2018`, `model_2019`, `model_2020`), consider using a list or data frame instead.

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

# Bad
first_day_of_the_month
djm1
```

Where possible, avoid re-using names of common 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

### Commas

Always put a space after a comma, never before, just like in regular English.  

```{r, eval = FALSE}
# Good
x[, 1]

# Bad
x[,1]
x[ ,1]
x[ , 1]
```

### Parentheses

Do not put spaces inside or outside parentheses for regular function calls.

```{r, eval = FALSE}
# Good
mean(x, na.rm = TRUE)

# Bad
mean (x, na.rm = TRUE)
mean( x, na.rm = TRUE )
```

Place a space before and after `()` when used with  `if`, `for`, or `while`.

```{r, eval = FALSE}
# Good
if (debug) {
  show(x)
}

# Bad
if(debug){
  show(x)
}
```

Place a space after `()` used for function arguments:

```{r, eval = FALSE}
# Good
function(x) {}

# Bad
function (x) {}
function(x){}
```

### Embracing

The embracing operator, `{{ }}`, should always have inner spaces to help emphasise its special behaviour:

```{r, eval = FALSE}
# Good
max_by <- function(data, var, by) {
  data %>%
    group_by({{ by }}) %>%
    summarise(maximum = max({{ var }}, na.rm = TRUE))
}

# Bad
max_by <- function(data, var, by) {
  data %>%
    group_by({{by}}) %>%
    summarise(maximum = max({{var}}, na.rm = TRUE))
}
```


### Infix operators

Most infix operators (`==`, `+`, `-`, `<-`, etc.) should always be surrounded by
spaces:

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

# Bad
height<-feet*12+inches
mean(x, na.rm=TRUE)
```

There are a few exceptions, which should never be surrounded by spaces:

*   The operators with [high precedence][syntax]: `::`, `:::`, `$`, `@`, `[`, 
    `[[`, `^`, unary `-`, unary `+`, and `:`.
  
    ```{r, eval = FALSE}
    # Good
    sqrt(x^2 + y^2)
    df$z
    x <- 1:10

    # Bad
    sqrt(x ^ 2 + y ^ 2)
    df $ z
    x <- 1 : 10
    ```
  
*   Single-sided formulas when the right-hand side is a single identifier:

    ```{r, eval = FALSE}
    # Good
    ~foo
    tribble(
      ~col1, ~col2,
      "a",   "b"
    )

    # Bad
    ~ foo
    tribble(
      ~ col1, ~ col2,
      "a", "b"
    )
    ```

    Note that single-sided formulas with a complex right-hand side do need a space:

    ```{r, eval = FALSE}
    # Good
    ~ .x + .y

    # Bad
    ~.x + .y
    ```

*   When used in tidy evaluation `!!` (bang-bang) and `!!!` (bang-bang-bang)
    (because have precedence equivalent to unary `-`/`+`)

    ```{r, eval = FALSE}
    # Good
    call(!!xyz)
    
    # Bad
    call(!! xyz)
    call( !! xyz)
    call(! !xyz)
    ```

*   The help operator

    ```{r, eval = FALSE}
    # Good
    package?stats
    ?mean
    
    # Bad
    package ? stats
    ? mean
    ```
    
### Extra spaces

Adding extra spaces is ok if it improves alignment of `=` or `<-`. 

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

# Also fine
list(
  total = a + b + c,
  mean = (a + b + c) / n
)
```

Do not add extra spaces to places where space is not usually allowed.

## Function calls

### Named arguments {#argument-names}

A function's arguments typically fall into two broad categories: one supplies 
the __data__ to compute on; the other controls the __details__ of computation. 
When you call a function, you typically omit the names of data arguments, 
because they are used so commonly. If you override the default value of an 
argument, use the full name:

```{r, eval = FALSE}
# Good
mean(1:10, na.rm = TRUE)

# Bad
mean(x = 1:10, , FALSE)
mean(, TRUE, x = c(1:10, NA))
```

Avoid partial matching.

### Assignment

Avoid assignment in function calls:

```{r, eval = FALSE}
# Good
x <- complicated_function()
if (nzchar(x) < 1) {
  # do something
}

# Bad
if (nzchar(x <- complicated_function()) < 1) {
  # do something
}
```

The only exception is in functions that capture side-effects:

```{r, eval = FALSE}
output <- capture.output(x <- f())
```


## Control flow

### Code blocks {#indenting}

Curly braces, `{}`, define the most important hierarchy of R code. To make this 
hierarchy easy to see:

* `{` should be the last character on the line. Related code (e.g., an `if` 
  clause, a function declaration, a trailing comma, ...) must be on the same
  line as the opening brace.

* The contents should be indented by two spaces.

* `}` should be the first character on the line.

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

if (y == 0) {
  if (x > 0) {
    log(x)
  } else {
    message("x is negative or zero")
  }
} else {
  y^x
}

test_that("call1 returns an ordered factor", {
  expect_s3_class(call1(x, y), c("factor", "ordered"))
})

tryCatch(
  {
    x <- scan()
    cat("Total: ", sum(x), "\n", sep = "")
  },
  interrupt = function(e) {
    message("Aborted by user")
  }
)

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

if (y == 0)
{
    if (x > 0) {
      log(x)
    } else {
  message("x is negative or zero")
    }
} else { y ^ x }
```

### If statements

* If used, `else` should be on the same line as `}`.

* `&` and `|` should never be used inside of an `if` clause because they can
  return vectors. Always use `&&` and `||` instead.
  
* NB: `ifelse(x, a, b)` is not a drop-in replacement for `if (x) a else b`.
  `ifelse()` is vectorised (i.e. if `length(x) > 1`, then `a` and `b`  will be 
  recycled to match) and it is eager (i.e. both `a` and `b` will always be 
  evaluated). 
  
    If you want to rewrite a simple but lengthy `if` block:
        
    ```{r, eval = FALSE}
    if (x > 10) {
      message <- "big"
    } else {
      message <- "small"
    }
    ```
    
    Just write it all on one line:
    
    ```{r, eval = FALSE}
    message <- if (x > 10) "big" else "small"
    ```

### Inline statements {#inline-statements}

It's ok to drop the curly braces for very simple statements that fit on one line, as long as they don't have side-effects.

```{r}
# Good
y <- 10
x <- if (y < 20) "Too low" else "Too high"
```

Function calls that affect control flow (like `return()`, `stop()` or `continue`) should always go in their own `{}` block:

```{r}
# Good
if (y < 0) {
  stop("Y is negative")
}

find_abs <- function(x) {
  if (x > 0) {
    return(x)
  }
  x * -1
}

# Bad
if (y < 0) stop("Y is negative")

if (y < 0)
  stop("Y is negative")

find_abs <- function(x) {
  if (x > 0) return(x)
  x * -1
}
```

### Implicit type coercion

Avoid implicit type coercion (e.g. from numeric to logical) in `if` statements:

```{r, eval = FALSE}
# Good
if (length(x) > 0) {
  # do something
}

# Bad
if (length(x)) {
  # do something
}
```

### Switch statements

* Avoid position-based `switch()` statements (i.e. prefer names).
* Each element should go on its own line.
* Elements that fall through to the following element should have a space after `=`.
* Provide a fall-through error, unless you have previously validated the input.

```{r, eval = FALSE}
# Good 
switch(x, 
  a = ,
  b = 1, 
  c = 2,
  stop("Unknown `x`", call. = FALSE)
)

# Bad
switch(x, a = , b = 1, c = 2)
switch(x, a =, b = 1, c = 2)
switch(y, 1, 2, 3)
```

## Long lines

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.

If a function call is too long to fit on a single line, use one line each for 
the function name, each argument, and the closing `)`. 
This makes the code easier to read and to change later. 

```{r, eval = FALSE}
# Good
do_something_very_complicated(
  something = "that",
  requires = many,
  arguments = "some of which may be long"
)

# Bad
do_something_very_complicated("that", requires, many, arguments,
                              "some of which may be long"
                              )
```

As described under [Named arguments](#argument-names), you can omit the argument names
for very common arguments (i.e. for arguments that are used in almost every 
invocation of the function). Short unnamed arguments can also go on the same 
line as the function name, even if the whole function call spans multiple lines.

```{r, eval = FALSE}
map(x, f,
  extra_argument_a = 10,
  extra_argument_b = c(1, 43, 390, 210209)
)
```

You may also place several arguments on the same line if they are closely 
related to each other, e.g., strings in calls to `paste()` or `stop()`. When 
building strings, where possible match one line of code to one line of output. 

```{r, eval = FALSE}
# Good
paste0(
  "Requirement: ", requires, "\n",
  "Result: ", result, "\n"
)

# Bad
paste0(
  "Requirement: ", requires,
  "\n", "Result: ",
  result, "\n")
```

## Semicolons

Don't put `;` at the end of a line, and don't use `;` to put multiple commands 
on one line.

## Assignment

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

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

# Bad
x = 5
```

## Data

### Character vectors

Use `"`, not `'`, for quoting text. The only exception is when the text already 
contains double quotes and no single quotes.

```{r, eval=FALSE}
# Good
"Text"
'Text with "quotes"'
'<a href="http://style.tidyverse.org">A link</a>'

# Bad
'Text'
'Text with "double" and \'single\' quotes'
```

### Logical vectors

Prefer `TRUE` and `FALSE` over `T` and `F`.

## Comments

Each line of a comment should begin with the comment symbol and a single 
space: `# `

In data analysis code, use comments to record important findings and analysis 
decisions. If you need comments to explain what your code is doing, consider 
rewriting your code to be clearer. If you discover that you have more comments 
than code, consider switching to [R Markdown][rmd].

[syntax]: https://rdrr.io/r/base/Syntax.html
[rmd]:    https://rmarkdown.rstudio.com/