2  Style Guide

2.1 ESQlabs Style Guide

At ESQlabs, we follow the tidyverse style guide with very few changes. The following sections outline the most important differences with the Tidyverse guide. To learn more about original Tidyverse style guide, please refer to the Tidyverse style highlights section.

2.1.1 Syntax

2.1.1.1 Naming Conventions

For simplicity, users should use snake_case as recommended by the tidyverse style (this is not the case for developers that should follow the OSPS-R coding standards).

However the naming style depends on the type of object: 

• Variable and function names should use only letters and numbers. Use snake_case to separate words within a name:

  # Good
  fit_model <- function() {
    # code
  }
  results_df <- data.frame()

• True constant variables should use ALL_CAPS casing:

  # Good
  CONSTANT_VAR <- 1

• Use short meaningful and understandable names. The code should read as a story and only some well-known abbreviations should be used:

  # Good
  pk_data <- read_excel("pkDataFile.xls")
  
  # Bad
  pharmacokinetics_data <- read_excel("pkDataFile.xls") # Too long

2.1.1.2 Spacing

Because it is not explicitly said in the tidyverse guideline and for improved code readability, use the following indentation settings:

• Use spaces instead of tabs
• Use indentation width of 2

You can check that these settings are correctly set in Tools > Global Options > Code > Editing:

2.1.2 Functions

2.1.2.1 return()

Prefer using return() for explicitly returning result, although you can rely on R to implicitly return the result of the last evaluated expression in a function.

2.1.3 Line length

Avoid having long lines. Restrict yourself to 120 characters (instead of the usual limit of 80 characters).

2.2 Tidyverse Style Highlights

The tidyverse style guide is the reference regarding R coding style. The guide is quite comprehensive, with a lot of examples of what to do and what not to do. If you never read it, you should read it at least once.

Here we highlight the main aspects of the tidyverse style guide, in a very synthetic way. This is to be used more as a checklist. Please refer to the full tidyverse style guide for more details and examples.

Examples listed here might have been adapted, when appropriate, to follow ESQlabs’ style instead of the Tidyverse one.

2.2.1 Files

2.2.1.1 Names

• File names should be meaningful and end in .R.
• Avoid using special characters and spaces in file names. Stick with numbers, letters, -, and _.
• Prefer file names that are all lower case.
• If files should be run in a particular order, prefix them with numbers.

# Good
01_preprocessing.R
02_fit_models.R
utility_functions.R

2.2.1.2 Structure

• Use sections (commented lines of - and =) to break up your file into easily readable chunks.
• Load all needed packages at the very beginning of the file (and don’t scatter them in your code).

# Load packages -----------------------
library(esqlabsR)

# Load Data ---------------------------

# Plot data ---------------------------
## Plot time profile ------------------

## Plot observed vs simulated ---------

2.2.2 Syntax

2.2.2.1 Object Names

• Variable names should be nouns and function names should be verbs.
• Names should be concise and meaningful (this is not easy!).
• Use underscores _ to separate words within a name (so called snake case).
• Avoid re-using names of common functions and variables.

# Good 
# Variable names (nouns)
day_one
day_1

# Function names (verbs)
add_rows()
permute()

# Bad
first_day_of_the_month # too long
d1 # not explicit
row_adder() # not a verb
T <- FALSE # reusing of common name
mean <- 10 # reusing of common function

2.2.2.2 Assignment

• Use <-, not =, for assignment.

2.2.2.3 Spacing

• Always put a space after a comma, never before.
• Most infix operators (+, -, /, *, <-, =, ==, &, &&, |, ||, >, <, >=, <=, %in%, etc.) should always be surrounded by spaces.
• Some infix operators with high precedence (^, :, $, [], [[]], ::, :::, @, etc.) should never be surrounded by spaces.
• Adding extra spaces is allowed only if it improves alignment of <- or =.

# Good
my_data[, 1]
x <- 1:10
y <- c(1, 5, 8)

height <- (feet * 12) + inches
bmi <- weight^2 / height

2.2.2.3.1 Functions

• Do not put spaces inside or outside parentheses for regular function calls.
• Place spaces around = when used in function calls.
• When you call a function, you can 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.
• Place a space after () used for function arguments definition.

# Good
mean(x, na.rm = TRUE)

my_function <- function(x, y) {
  # As usual code is indented by two spaces
}

2.2.2.3.2 Statements

• Place a space before and after () when used with if, for, or while.
• If used, else should be on the same line as }.
• & and | should never be used inside of an if clause because as they can return vectors. Always use && and || instead.
• 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
if (y < 0 && debug) {
  message("y is negative")
} else {
  message("y is positive or zero")
}

message <- if (x > 10) "big" else "small"

2.2.2.3.3 Code blocks

• An opening curly brace { should always be followed by a new line. Related code (e.g., an if clause, a function declaration, …) must be on the same line as the opening brace.
• A closing curly brace } should always go on its own line, unless it’s followed by else.
• Always indent the code inside curly braces by two spaces.

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

2.2.2.3.4 Pipes

• Pipes %>% should always have a space before it, and should usually be followed by a new line.
• After the first step, each line should be indented by two spaces.

iris %>%
  group_by(Species) %>%
  summarize_if(is.numeric, mean) %>%
  ungroup() %>%
  gather(measure, value, -Species) %>%
  arrange(value)

2.2.2.3.5 ggplot2

• + should always have a space before it, and should be followed by a new line (such that each layer is on its own line).
• After the first step, each line should be indented by two spaces.

ggplot(iris, aes(x = Sepal.Width, y = Sepal.Length)) +
  geom_point() +
  labs(x = "Sepal Width (cm)", y = "Sepal Length (cm)")

2.2.3 Long Lines

2.2.3.1 Function call

• 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"
)

2.2.3.2 Function definition

• If a function definition is too long to fit on a single line use either:
  • function indent (place each argument on its own line and indent to match the opening ( of the function). This is the preferred method.
  • double-indent (place each argument on its own double indented line)
• In both cases the trailing ) and leading { should go on the same line as the last argument.

# Function indent (preferred method)
long_function_name <- function(a = "a long argument",
                               b = "another argument",
                               c = "another long argument") {
  # As usual code is indented by two spaces
}

# Double indent
long_function_name <- function(
    a = "a long argument",
    b = "another argument",
    c = "another long argument") {
  # As usual code is indented by two spaces
}

2.2.4 Comments

• Explain the “why” not the “what” or “how”.
• Each line of a comment should begin with the comment symbol # and a single space.
• Comments should be in sentence case, and only end with a full stop if they contain at least two sentences.

2.2.5 Others

• Prefer TRUE and FALSE over T and F.
• Use ", not ', for quoting text.
• Don’t put ; at the end of a line, and don’t use ; to put multiple commands on one line.