File names

File names end in .R and are meaningful about their content:

Good:

• string-algorithms.R
• utility-functions.R

Bad:

• foo.R
• foo.Rcode
• stuff.R

Function names

Preferrably function names consist of lowercase words separated by an underscore. Using dot (.) separator is avoided as this confuses with the use of generic (S3) functions. It also prevents name clashes with existing functions from the standard R packages. Camel-case style is also suitable especially for predicate functions returning a boolean value. Function names ideally start with verbs and describe what the function does.

# GOOD
create_summary()
calculate_avg_clicks()
find_string()
isOdd()

# BAD
crt_smmry()
find.string()
foo()

Variable names

Variable names consist of lowercase words separated by an underscore or dot. Camel-case style is also suitable especially for variables representing boolean values. Variable names ideally are attributed nouns and describe what (state) they store.

Good:

summary_tab
selected_timeframe
out.table
hasConverged

Bad:

smrytab
selTF
outtab
hascnvrgd

Name clashes with existing R base functions are avoided:

# Very bad:
T <- FALSE
c <- 10
mean <- function(a, b) (a + b) / 2
file.path <- "~/Downloads" # clashes with base::file.path function

Loop variables or function arguments can be just single letters if

• the naming follows standard conventions
• their meaning is clear
• understanding is preserved

otherwise use longer variable names.

# GOOD
for (i in 1:10) print(i)
add <- function(a, b) a + b
rnorm <- function(n, mean = 0, sd = 1)

# BAD
for (unnecessary_long_variable_name in 1:10) print(unnecessary_long_variable_name)
add <- function(a1, x7) a1 + x7
rnorm <- function(m, n = 0, o = 1)

Function definitions

Function definitions first list arguments without default values, followed by those with default values. In both function definitions and function calls, multiple arguments per line are allowed; line breaks are only allowed between assignments.

# GOOD
rnorm <- function(n, mean=0, sd=1)
pnorm <- function(q, mean=0, sd=1, 
                  lower.tail=TRUE, log.p=FALSE)

# BAD
mean <- function(mean=0, sd=1, n)           # n should be listed first
pnorm <- function(q, mean=0, sd=1, lower.tail=
                  TRUE, log.p=FALSE)

Function calls

When calling a function, the meaning of the function call and arguments should be clear from the call, that is, usually function arguments beyond the first are explicitly named or at least invoked with a meaningful variable name, for example, identical to the name of the function argument:

# GOOD
rnorm(100, mean=1, sd=2)
identical(1, 1.0)   # no need for explicit naming as meaning of call is clear

mean <- 1
sd <- 2
std.dev <- sd
rnorm(100, mean, sd)
rnorm(100, mean, std.dev)

# BAD
rnorm(100, 1, 2)

Assignment

For any assignment, the arrow <- is preferable over the equal sign =.

x <- 5  # GOOD
x  = 5  # OK

Semicolons are never used.

# BAD
x <- 5; y <- 10; z <- 3  # break into three lines instead

Spacing around …

# GOOD
v <- c(1, 2, 3)
m[1, 2]

# BAD
v <- c(1,2,3)
m[1 ,2]

# GOOD
# Spacing according to semantically connected groups
x <- 1:10
base::get
average <- mean(feet/12 + inches, na.rm=TRUE)

# Using more spaces - also ok
average <- mean(feet / 12 + inches, na.rm = TRUE)
# BAD
x <- 1 : 10
base :: get
average<-mean(feet/12+inches,na.rm=TRUE)

# GOOD
if (debug) print(x)
plot(x, y)

# Special case arithmetic expression:
2 + (a+b)/(c+d) + z/(1+a)

# BAD
if(debug)print (x)
plot (x, y)

# GOOD
if (debug) print(x)
diamonds[3, ]
diamonds[, 4]

# BAD
if ( debug ) print( x )
diamonds[ ,4]

# GOOD
for (x in letters[1:10]) {
    print(x)
}

add <- function(x, y) {
    x + y
}

add <- function(x, y)
{
    x + y
}

# BAD
add <- function(x, y) {x + y}

Indentation

Code is indented with ideally four, but at least two spaces. Usually using four spaces provides better readability than two spaces especially the longer the indented code-block gets.

# Four-space indent:
for (i in seq_len(10)) {
    if (i %% 2 == 0) {
        print("even")
    } else {
        print("odd")
    }
}

# The same code-block using two-space indent:
for (i in seq_len(10)) {
  if (i %% 2 == 0) {
    print("even")
  } else {
    print("odd")
  }
}

Extended indendation: when a line break occurs inside parentheses, align the wrapped line with the first character inside the parenthesis:

fibonacci <- c(1, 1, 2, 3, 5,
               8, 13, 21, 34)

Line length

Ideally, the code does not exceed 80 characters per line. This fits comfortably on a printed page with a reasonably sized and therefore can be easily processed by a human, which tend to read line by line. Longer comments are simply broken into several lines:

# Here is an example of a longer comment, which is just broken into two lines
# in order to serve the 80 character rule.

Long variable names can cause problems regarding the 80 characters limit. In such cases, one simple yet effective solution is to use interim results, which are saved in a new meaningful variable name. This at the same time often improves the readability of the code. For example:

# Longer statement
total.cost <- hotel.cost + cost.taxi + cost.lunch + cost.airplane +
    cost.breakfast + cost.dinner + cost.car_rental

# Solution with interim result
travel.cost <- cost.taxi + cost.airplane + cost.car_rental
food.cost <- cost.breakfast + cost.lunch + cost.dinner
total.cost <- travel.cost + food.cost + hotel.cost

Similarly, four-space indenting in combination with multiple nested code-blocks can cause problems to maintain the 80 character limit and may require to relax this rule in such cases. At the same time, however, multiple nested code-blocks should be avoided in the first place, because with more nesting the code usually gets harder to understand.

Block length

Each functionally connected block of code (usually a function block) should not exceed a single screen (about 50 lines of code). This allows the code to be read and understood without having to line-scroll. Exceeding this limit usually is a good indication that some of the code should be encapsulated (refactorized) into a separate unit or function. Doing so, not only improves the readability of the code but also flexibilizes (and thereby simplifies) further code development. In particular, single blocks that are separated by comments, often can be refactorized into functions, named similar to the comment, for example:

Long single-block version:

# Sub-block 1: simulate data for some model
x <- 1:100
y <- rnorm(length(x))
.
.
.
longer code block generating some data
.
.
.
data <- ...

# Sub-block 2: plot the resulting data points
ylims <- c(0, 30)
p <- ggplot(data) +
.
.
.
longer code block defining plot object
.
.
.

# Sub-block 3: format results and export to Excel file
outFile <- "output.xlsx"
.
.
export to Excel file
.
.

The singe-block version may exceed a single page and requires a lot of comments just to separate each step visually, but even with this visual separation, it will be unnecessary difficult for a second person to understand the code, because allthough the code might be entirely sequential, he possibly will end up jumping back and forth within the block to get an understanding of it. In addition, if parts of the block are changed at a later time point, the code can easily get out of sync with the comments.

Refactorized version:

# Simulate data, plot it and export it to Excel file
data.sim <- simulate_data(x = 1:100, y = rnorm(length(x)), ...)
plot_simulated_data(data.sim, ylims = c(0, 30), ...)
write_results_into_table(data.sim, outFile="output.xlsx")

In the refactorized version each sub-block was put into a separate function (not shown), which is now called in place. In contrast to the single-block version, each of these functions can be re-used, tested and have their own documentation. Since each of such functions encapsulate their own environment, the second (refactorized) design is also less vulnerable to side-effects between blocks. A second person can now read and understand function by function without having to worry about the rest of the block.

Last but not least, the block comments in the single-block versions could be transformed into function names so that the documentation is now part of the code and as such no longer can get out of sync with it.

Packages and namespaces

Whenever the :: operator is used, the namespace of the corresponding package is loaded but not attached to the search path.

tools::file_ext("test.txt")     # loads the namespace of the 'tools' package,
## [1] "txt"
search()                        # but does not attach it to the search path
## [1] ".GlobalEnv"        "package:stats"     "package:graphics" 
## [4] "package:grDevices" "package:utils"     "package:datasets" 
## [7] "package:methods"   "Autoloads"         "package:base"
file_ext("test.txt")            # and thus produces an error if called without namespace prefix
## Error in file_ext("test.txt"): could not find function "file_ext"
# base::mean and stats::rnorm work, because base and stats namespaces are
# loaded and attached by default:
mean(rnorm(10))
## [1] -0.04888008

In contrast, the library and require commands both load the package’s namespace but also attach its namespace to the search path, which allows to refer to functions of the package without using the :: operator.

library(tools)                  # loads namespace and attaches it to search path
search()
##  [1] ".GlobalEnv"        "package:tools"     "package:stats"    
##  [4] "package:graphics"  "package:grDevices" "package:utils"    
##  [7] "package:datasets"  "package:methods"   "Autoloads"        
## [10] "package:base"
file_ext("test.txt")            # now works
## [1] "txt"

Since a call to a function shall not alter the search path, library or require statements are not allowed in functions used in R packages. In contrast, library statements are suitable for local (data analysis) R scripts especially if a specific function is used frequently. An alternative is to locally re-map the frequently used function:

file_ext <- tools::file_ext
file_ext("test.txt")
## [1] "txt"
file_ext("test.docx")
## [1] "docx"
file_ext("test.xlsx")
## [1] "xlsx"