House style and naming

The grammar accepts more than one way of writing several things. This page picks one of each. None of these rules changes what a script does. They exist so that two scripts written by two people read alike.

Every rule here is one you can break without an error. A rule you cannot break is not style, it is syntax, and it belongs in the language reference instead.

Pick one spelling for each logical operator

Each of the three logical operators has a symbol form and a word form. The two forms are the same token, so the interpreter cannot tell them apart. Write the word forms.

Practice to avoid:

signal = close > open && volume > 0
strong = signal || close > high[1]

House style:

signal = close > open and volume > 0
strong = signal or close > high[1]

Mixing the two spellings in one file makes a reader stop and check whether the difference means something. It does not.

Declare a function with def

The declaration keyword is optional. You may write def, write func, or write neither. Write def, so that a declaration can be found by searching for it.

Practice to avoid:

spread(series float h, series float l) => h - l

House style:

def spread(series float h, series float l) => h - l

Use the arrow form for a single expression

A function body is either a braced block or a single expression after an arrow. Use the arrow while the body is one expression. Open a brace as soon as there is a second statement.

Practice to avoid:

def midpoint(series float h, series float l) {
  return (h + l) / 2
}

House style:

def midpoint(series float h, series float l) => (h + l) / 2

State the form type on every parameter

A parameter must state its data type. The grammar gives you no way to leave that out. The form type in front of it is optional, and so is a default value after it.

Write the form type anyway. A reader can then tell from the signature alone whether a value stays fixed for the whole run or changes bar by bar.

Practice to avoid:

def spread(float h, float l) => h - l

House style:

def spread(series float h, series float l) => h - l

Name your arguments, except step

Where a call takes more than two arguments, name them at the call site. Two calls that look alike can take their remaining arguments in a different order, and a named argument removes the question.

One argument cannot be named. The step parameter of the integer and float input functions must be passed by position, because step is a reserved word the grammar uses for counted loops. Naming it is a parse error.

Put the declaration first

A script declares itself with indicator() and puts a value on the chart with plot(). Put the declaration on the first line, ahead of everything else.

How these rules were chosen

A style rule has to be checkable against the language rather than against habit. Each rule above names something the grammar accepts, and something else the grammar also accepts you doing instead.

That test matters more than it sounds. The keyword that makes a value persist across bars is static, and a declaration beginning var does not compile. A style guide that recommends var is worse than no style guide at all, because it costs the reader a compile error rather than an argument about layout.

A script in house style

indicator("Midpoint")
def midpoint(series float h, series float l) => (h + l) / 2
plot(midpoint(high, low))