Whitespace has put the kettle on

Whitespace has opinions. Left alone with a new project, it will eventually form a committee.

I would rather give Pooka one formatter and let the committee go home.

Lay out the decisions

A formatter receives a program that already has structure. Its task is to choose a readable layout while keeping the program’s meaning intact. Brackets, comments and string contents do not become negotiable because a line is inconveniently wide.

label(count: Int) -> String {
  match count {
    0 -> "no visitors"
    1 -> "one visitor"
    _ -> "several visitors"
  }
}

main() {
  assert label(1) == "one visitor"
}

Here the alternatives have separate lines, and declarations have a blank line between them. The reader can find the decisions without following a trail of closing braces across the page.

Let a group break together

pooka format src test
pooka format --check src test

The first command writes the chosen layout. The second checks it without rewriting files.

Long argument lists present a different problem. The formatter needs to consider whether a group fits, then choose a broken layout if it does not. Deciding each comma independently can produce a staircase that nobody ordered.

Gleam is a useful reference for this sort of restraint. A predictable convention saves time precisely because there is so little to discuss each time it is applied.

Ask it the same question twice

format(source) = first_result
format(first_result) = first_result

There are useful tests beyond comparing a file with a snapshot. Formatting twice should produce the same bytes as formatting once. A second pass that moves things again means the first pass did not settle the question.

Comments deserve their own tests. They can explain the declaration below them or a particular expression beside them. Moving one across a boundary can damage the explanation while leaving the executable program perfectly intact.

A formatter cannot make a confusing design clear. It can remove some smaller obstacles between the design and the person trying to understand it.

Whitespace has accepted this arrangement. It would still like a say in the tea.

— Peregrine Finch