R Language - Code Specification (Google's R Style Guide)

R is a high-level programming language mainly used for statistical computing and graphics. The goal of the R programming style guide is to make our R code easier to read, share, and verify. The following R code rules were designed under Google's entire R collaborative user community.

Notation and Naming

File names

File names should end in .R and, of course, be meaningful.
GOOD: predict_ad_revenue.R
BAD: foo.R

Identifiers

Do not use underscore (_) or hyphen (-) identifiers. Identifiers should follow the following naming conventions. The preferred forms of variable names are all lowercase letters and words separated by dots (variable.name), but variableName; function names with initial uppercase letters and no dots (FunctionName);

variable.name is preferred, variableName is accepted
GOOD: avg.clicks
OK: avgClicks
BAD: avg_Clicks

FunctionName
GOOD: CalculateAvgClicks
BAD: calculate_avg_clicks , calculateAvgClicks
Make function names verbs.
Exception: When creating a classed object, the function name

Syntax

Maximum length of each line (Line Length)

The maximum line length is 80 characters.

Indentation

When indenting code, use two spaces. Never use tabs or mix tabs and spaces. Exception: When a newline occurs inside parentheses, align it with the first character inside the parentheses.

Spacing

When using all binary operators (such as =, +, -, <, etc.) use spaces at both ends. Exception: When the symbol = is a function call, the passed parameters are not separated by spaces. Do not separate spaces before the symbol ",", but add a space GOOD
after "," :

tab.prior <- table(df[df$days.from.opt < 0, "campaign.id"]) 
total <- sum(x[, 1]) 
total <- sum(x[1, ])

BAD:

tab.prior <- table(df[df$days.from.opt<0, "campaign.id"])  # Needs spaces around '<' 
tab.prior <- table(df[df$days.from.opt < 0,"campaign.id"])  # Needs a space after the comma
tab.prior<- table(df[df$days.from.opt < 0, "campaign.id"])  # Needs a space before <
tab.prior<-table(df[df$days.from.opt < 0, "campaign.id"])  # Needs spaces around <
total <- sum(x[,1])  # Needs a space after the comma 
total <- sum(x[ ,1])  # Needs a space after the comma, not before

Add a space before the opening parenthesis, except for the call to the function
GOOD:

if (debug)

BAD:

if(debug)

Extra spacing (i.e., more than one space in a row) is okay if it improves alignment of equals signs or arrows (<-).

plot(x    = x.coord,     
     y    = data.mat[, MakeColName(metric, ptiles[1], "roiOpt")],     
     xlab = "dates", 
     ylab = metric,
     main = (paste(metric, " for 3 samples ", sep = "")))

Curly Braces

An opening parenthesis should never go on its own line; a closing parenthesis should always be on a line. You can omit curly braces when a block of code is a single statement. However, you have to consider other identical situations to be consistent.

if (is.null(ylim)) {  ylim <- c(0, 0.06) }

xor (but not both)

if (is.null(ylim))  ylim <- c(0, 0.06)

Always begin the body of a block on a new line.
BAD:

if (is.null(ylim)) ylim <- c(0, 0.06) 
if (is.null(ylim)) {ylim <- c(0, 0.06)}

Curly braces and else
An else statement should always be surrounded by curly braces on the same line.
Good:

if (condition) {  
  one or more lines 
} else {  
  one or more lines 
}

Bad:

if (condition) {  
  one or more lines 
} 
else {  
  one or more lines 
}

Assignment

Use <-, not =, for assignment.
GOOD:

x <- 5

BAD:

x = 5

Organization

General Layout and Ordering

If everyone used the same general order, we were able to read and understand each other's scripts faster and easier. The general start should include:

Copyright Notice Notes
Author comments
Comments on file descriptions, including program purpose, input and output
source() and library() declarations
function definition
Executed statement

Unit tests should be in a separate file named originalfilename_test.R.

Commenting Guidelines

Short comments can be placed after the code , separated by a space + # + space, and longer comments can be on a separate line.

# Create histogram of frequency of campaigns by pct budget spent. 
hist(df$pct.spent,    
     breaks = "scott",  # method for choosing number of buckets     
     xlab   = "Fraction of budget spent",     
     ylab   = "Frequency (count of campaignids)")

Function Definitions and Calls

A function definition should list parameters without default values first, followed by those with default values.
In function definitions and function calls, multiple parameters are allowed on one line, but newlines are only allowed between parameters.
GOOD:

PredictCTR <- function(query, property, num.days,                                              
                       show.plot = TRUE)

BAD:

PredictCTR <- function(query, property, num.days, show.plot =     
                       TRUE)

Ideally, unit tests should be called as sample functions (shared library routines).

Function Documentation

A section comment should be included below the function definition. These comments should contain a description of the function, a description of the function's parameter list (including data types), and a description of the return value. These comments should be descriptive enough that the caller can understand how to call the function by reading the comments.

Example

CalculateSampleCovariance <- function(x, y, verbose = TRUE) {  
  # Computes the sample covariance between two vectors.  
  #  
  # Args:  
  #   x: One of two vectors whose sample covariance is to be calculated.  
  #   y: The other vector. x and y must have the same length, greater than one,  
  #      with no missing values.  
  #   verbose: If TRUE, prints sample covariance; if not, not. Default is TRUE.  
  # 
  # Returns:  
  #   The sample covariance between x and y.  

  n <- length(x)  
  # Error handling  
  if (n <= 1 || n != length(y)) {   
    stop("Arguments x and y have different lengths: ",
         length(x), " and ", length(y), ".")     
  }
  if (TRUE %in% is.na(x) || TRUE %in% is.na(y)) {  
    stop(" Arguments x and y must not have missing values.") 
  }
  covariance <- var(x, y)  
  if (verbose)    
    cat("Covariance = ", round(covariance, 4), ".\n", sep = "")  
  return(covariance) 
}

Functions

Errors should be notified with stop()

last words

Use common sense and BE CONSISTENT.

If you are editing code, take a few minutes to look at the code around you and determine its style. If others use spaces around their if clauses, you should, too. If their comments have little boxes of stars around them, make your comments have little boxes of stars around them, too.

The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on what you are saying, rather than on how you are saying it. We present global style rules here so people know the vocabulary. But local style is also important. If code you add to a file looks drastically different from the existing code around it, the discontinuity will throw readers out of their rhythm when they go to read it. Try to avoid this.

OK, enough writing about writing code; the code itself is much more interesting. Have fun!