2 Syntax

2.1 Object names

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

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

Generally, variable names should be nouns and function names should be verbs. Strive for names that are concise and meaningful (this is not easy!).

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

2.2 Spacing

2.2.1 Commas

Always put a space after a comma, never before, just like in regular English.

2.2.2 Parentheses

Do not put spaces inside or outside parentheses for regular function calls.

Place a space before and after () when used with if, for, or while.

Place a space after () used for function arguments:

2.2.3 Infix operators

Most infix operators (==, +, -, <-, etc.) should always be surrounded by spaces:

There are a few exceptions, which should never be surrounded by spaces:

2.2.4 Extra spaces

Adding extra spaces ok if it improves alignment of = or <-.

Do not add extra spaces to places where space is not usually allowed.

2.3 Argument names

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:

Avoid partial matching.

2.4 Indenting

Curly braces, {}, define the most important hierarchy of R code. To make this hierarchy easy to see, always indent the code inside {} by two spaces.

A symmetrical arrangement helps with finding related braces: the opening brace is the last, the closing brace is the first non-whitespace character in a line.
Code that is related to a brace (e.g., an if clause, a function declaration, a trailing comma, …) must be on the same line as the opening brace.

It’s ok to drop the curly braces if you have a very simple and short if statement that fits on one line. If you have any doubt, it’s better to use the full form.

2.5 Long lines

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.

As described under Argument names, 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.

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.

2.6 Assignment

Use <-, not =, for assignment.

2.7 Semicolons

Don’t put ; at the end of a line, and don’t use ; to put multiple commands on one line.

2.8 Quotes

Use ", not ', for quoting text. The only exception is when the text already contains double quotes and no single quotes.

2.9 Comments

In data analysis code, use comments to record important findings and analysis decisions. If you need comments to explain what your code is doing, consider rewriting your code to be clearer. If you discover that you have more comments than code, considering switching to RMarkdown.