34.9 White space
Stan allows spaces between elements of a program. The white space
characters allowed in Stan programs include the space (ASCII
0x20), line feed (ASCII 0x0A), carriage return
(0x0D), and tab (0x09). Stan treats all whitespace
characters interchangeably, with any sequence of whitespace characters
being syntactically equivalent to a single space character.
Nevertheless, effective use of whitespace is the key to good program
layout.
Line breaks between statements and declarations
Each statement of a program should appear on its own line. Declaring multiple variables of the same type can be accomplished in a single statement with the syntax
real mu, sigma;No tabs
Stan programs should not contain tab characters. Using tabs to layout a program is highly unportable because the number of spaces represented by a single tab character varies depending on which program is doing the rendering and how it is configured.
Two-character indents
Stan has standardized on two space characters of indentation, which is the standard convention for C/C++ code.
34.9.1 Space between if, { and condition
Use a space after ifs. For instance, use if (x < y) {..., not
if(x < y){ ....
No space for function calls
There should not be space between a function name and the arguments
it applies to. For instance, use normal(0, 1), not normal (0,1).
Spaces around operators
There should be spaces around binary operators. For instance, use
y[1] = x, not y[1]=x, use (x + y) * z not
(x+y)*z.
Unary operators are written without a space, such as in -x, !y.
No spaces in type constraints
Another exception to the above rule is when the assignment operator
(=) is used inside a type constraint, such as
real<lower=0> x;Spaces should still be used in arithmetic and following commas, as in
real<lower=0, upper=a * x + b> x;Breaking expressions across lines
Sometimes expressions are too long to fit on a single line. In that case,
the recommended form is to break before an
operator,48
aligning the operator to a term above to indicate scoping.
For example, use the following form
vector[J] p_distance = Phi((distance_tolerance - overshot)
./ ((x + overshot) * sigma_distance))
- Phi((-overshot)
./ ((x + overshot) * sigma_distance));Here, the elementwise division operator (./) is aligned to clearly
signal the division is occuring inside the parethenesis, while the
subtraction indicates it is between the function applications (Phi).
For functions with multiple arguments, break after a comma and line the next argument up underneath as follows.
y[n] ~ normal(alpha + beta * x + gamma * y,
pow(tau,-0.5));Spaces after commas
Commas should always be followed by spaces, including in function arguments, sequence literals, between variable declarations, etc.
For example,
normal(alpha * x[n] + beta, sigma);is preferred over
normal(alpha * x[n] + beta,sigma);Unix newlines
Wherever possible, Stan programs should use a single line feed character to separate lines. All of the Stan developers (so far, at least) work on Unix-like operating systems and using a standard newline makes the programs easier for us to read and share.
Platform specificity of newlines
Newlines are signaled in Unix-like operating systems such as Linux and
Mac OS X with a single line-feed (LF) character (ASCII code point
0x0A). Newlines are signaled in Windows using two characters,
a carriage return (CR) character (ASCII code point 0x0D)
followed by a line-feed (LF) character.
This is the usual convention in both typesetting and other programming languages. Neither R nor BUGS allows breaks before an operator because they allow newlines to signal the end of an expression or statement.↩︎