Overview
Every rule, which ones --fix applies and which ones --check only reports.
Stanza formats statement lists inside blocks: function bodies, arrow block bodies, methods, static blocks, if, loop and try blocks, and switch clause bodies. The blank line rules never touch the gaps between top level statements, class members or namespace members. The braces rule does not stop there: a single statement control flow body at top level loses its braces too.
Applied by --fix
| rule | what it does |
|---|---|
after-multiline | a statement that spans several lines is followed by a blank line |
switch-clauses | one blank line between switch clauses; a fall through label with an empty body stays directly above the next label; a blank line between clauses is never removed |
edge-blank | no blank line right after { or right before } |
guard-join | a single-line declaration or assignment is followed directly by an if that references what it binds, whatever the body size and with or without else |
consume-join | a single-line declaration or assignment is followed directly by a return or switch that references what it binds |
use-join | a single-line declaration is followed directly by a loop, try or function declaration that references what it binds |
guard-chain | consecutive single-line guards (if with a one statement body and no else) have no blank line between them |
let-step | a let that joins the block below it gets a blank line above it, so it starts its own step |
after-guard | a single-line guard that returns, throws, continues or breaks is followed by a blank line, unless the next statement is an if or a jump (return, throw, break, continue) |
short-body | a block of two or three single-line statements has no blank lines, whether it is a function body, a nested block or a switch clause body. A braceless if or loop whose header and body each sit on one line counts as single-line here, because the formatter puts it on one line |
braces | a control flow body that is a single statement has no braces |
Reported by --check, Never Fixed
| rule | what it reports |
|---|---|
block-spacing | a multi-line block directly under a statement, when no join rule explains it. Guard chains, parallel if runs and the setBusy(true) then try { } finally { setBusy(false) } bracket are not reported |
wall | six or more consecutive single-line statements with no blank line |
--fix prints these findings too. It never changes the code for them.
How a Gap Is Decided
A gap is the space between two neighbouring statements in a list. One rule decides each gap. The rules are tried in a fixed order, and the first one with an opinion wins:
- short-body
- guard-chain
- after-multiline
- switch-clauses
- guard-join, consume-join and use-join
- after-guard
When none of them applies, the gap keeps the blank lines it has. let-step runs afterwards as a pass over the decided gaps. edge-blank looks at the space inside a block's braces rather than between statements, and braces runs on its own. A gap next to a statement under stanza-ignore is frozen: no rule touches it or reports it (see Directives).
stanza explain <file>:<line> prints the rule that decided a line and what it outranked. See Explain.
Facts That Cut Across Rules
- A multi-line declaration never joins the statement below it. after-multiline is tried before the join rules and wins.
- A statement is compact when it sits on one line, or when it is a braceless
ifwithoutelse, a bracelessforor a bracelesswhilewhose header is on one line and whose body is compact. A braceless two lineifis both compact and multi-line: it chains as a guard and counts towards a short body, and it also gets a blank line after it when nothing outranks that. - A name that is read only inside a nested function (a function expression, an arrow, a function declaration nested in the statement) does not count as read, so
const record = load()followed byif (ok) run(() => record)does not join. A shadowed name does not count either. An assignment to a member such asstate.count = 1joins when the same path,state.count, is read. - Comments stay attached to the statement below them as long as no blank line separates them. An inserted blank line goes above the leading comments, and a trailing comment on the same line moves with its statement. When a blank line already separates a comment from the statement under it, the statement is detached: the gap above it is never edited or reported.
- A statement that starts on the closing line of a multi-line statement is left alone.