R Style Guide

Style guide

Our group style guide is based on Hadley Wickham's guide but with slightly different naming guidelines because underscores are unpopular and a few specific naming conventions for our group.

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 wiki before using it.

Notation and naming

Package and Analysis Names

# Package name
conteName

# Analysis repository name primarily using package conteName
conteName_analysisName

File names

File (Rmarkdown files within analysis repos) names should be meaningful and end in .R or .Rmd

    # Good
    fit-models.R
    utility-functions.Rmd

    # Bad
    foo.r
    stuff.r

If files need to be run in sequence, prefix them with numbers:

    0-download.Rmd
    1-parse.Rmd
    2-explore.Rmd

Object names

Variable should be lowercase and should generally be nouns. Use an period (.) to separate words within a name. Strive for names that are concise and meaningful (this is not easy!).

# Good
day.one
day.1

# Bad
first_day_of_the_month
DayOne
dayone
djm1
day_one
day_1

Function names should be lower camel case. Generally, variable names should be nouns and function names should be verbs. ** This seemed to be what many people did, but now seems like people are switching to functions being named just like any other objects (as above) **

# Good
parseText
runModel
snip

# Bad
run_first_dataset_from_MA
day
parse.text
strp_name

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

# Bad
T <- FALSE
c <- 10
mean <- function(x) sum(x)

Syntax

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).

# 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.

# Good
x <- 1:10
base::get

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

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

# 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 (<-).

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).

# 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.

# 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:

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.

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

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.

# Good
x <- 5

# Bad
x = 5

Organisation

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.

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

# Load data ---------------------------

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