“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.
# 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!).
# 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.
# Bad T <- FALSE c <- 10 mean <- function(x) sum(x)
Always put a space after a comma, never before, just like in regular English.
# Good x[, 1] # Bad x[,1] x[ ,1] x[ , 1]
Do not put spaces inside or outside parentheses for regular function calls.
# 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.
# Good if (debug) { show(x) } # Bad if(debug){ show(x) }
Place a space after () used for function arguments:
# Good function(x) {} # Bad function (x) {} function(x){}
The embracing operator, {{ }}, should always have inner spaces to help emphasise its special behaviour:
# 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)) }
Most infix operators (==, +, -, <-, etc.) should always be surrounded by spaces:
# 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: ::, :::, $, @, [, [[, ^, unary -, unary +, and :.
# 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:
# 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:
# Good ~ .x + .y # Bad ~.x + .y
-
When used in tidy evaluation !! (bang-bang) and !!! (bang-bang-bang) (because have precedence equivalent to unary -/+)
# Good call(!!xyz) # Bad call(!! xyz) call( !! xyz) call(! !xyz)
-
The help operator
# Good package?stats ?mean # Bad package ? stats ? mean
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:
# Good mean(1:10, na.rm = TRUE) # Bad mean(x = 1:10, , FALSE) mean(, TRUE, x = c(1:10, NA))
Avoid partial matching.
Avoid assignment in function calls:
# 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:
output <- capture.output(x <- f())
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.
# 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 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:
if (x > 10) { message <- "big" } else { message <- "small" }
Just write it all on one line:
message <- if (x > 10) "big" else "small"
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.
# 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:
# 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 }
Avoid implicit type coercion (e.g. from numeric to logical) in if statements:
# Good if (length(x) > 0) { # do something } # Bad if (length(x)) { # do something }
- 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.
# 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)
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.
# 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, 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.
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.
# Good paste0( "Requirement: ", requires, "\n", "Result: ", result, "\n" ) # Bad paste0( "Requirement: ", requires, "\n", "Result: ", result, "\n")
Don’t put ; at the end of a line, and don’t use ; to put multiple commands on one line.
Use <-, not =, for assignment.
# Good x <- 5 # Bad x = 5
Use ", not ', for quoting text. The only exception is when the text already contains double quotes and no single quotes.
# Good "Text" 'Text with "quotes"' '<a href="//style.tidyverse.org">A link</a>' # Bad 'Text' 'Text with "double" and \'single\' quotes'
Prefer TRUE and FALSE over T and F.