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

Put a space before and after = when naming arguments in function calls. Always put a space after a comma, never before, just like in regular English.

Most infix operators (==, +, -, <-, etc.) should be surrounded by spaces. The exception are those with relatively high precedence: ^, :, ::, and :::. To highlight operator precedence, use parentheses rather than irregular spacing.

Put spaces around ~ in formulas, only omit the space in single-sided formulas where the rhs is a single identifier.

Place a space before ( when its used with a keyword like if, for or function:

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

Do not place spaces around code in parentheses or square brackets (unless there’s a comma, in which case see above).

Do not put a space after the tidy evaluation bang-bang (!!) or bang-bang-bang (!!!) operators.

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.