Reducing ambiguity and the rationale for the chosen options

[ryanatkn]

This post attempts to apply objective reasoning to subjective code formatting opinions, so caveats apply, and critical feedback and expressing disagreement are encouraged.

Update: since this post was written, tsv adopted a policy to inherit Svelte's choices. That still leaves a lot of divergences from Prettier, but means tsv inherits all of the Prettier options. This post explains my intended thought process for the remaining judgment calls (which are many).

Unlike most formatters, tsv has a non-configurable style - that choice is fixed, and takes after tools like gofmt and Python's Black. The environment-independent simplicity and predictability reasons are wins for my goals with the tool, and keeps this aspect of tsv minimal.

This means tsv must choose one canonical format that can't please everyone. The v0.1 behavior aligned more with my taste, but v0.2 takes a stance to inherit Svelte's choices, with some targeted tweaks to Prettier's behavior. For people who really want a different style, forking the tool is always an encouraged option (currently would be slightly unwieldy because there's no simple flags, but I'm open to supporting forks better on configuration).

The premise: when reading code, disambiguating constructs is one step of comprehension. Many patterns in code are repeated with different meaning, like ( and { and = and +, and the surrounding context is what informs the specific meaning. The claim here is that context clues quicken comprehension when reading code, in general, when not noisy or verbose.

Consider the closing curly brace:

}

A lone closing curly can indicate one of many constructs. Is it closing a function? An object or function in an assigment? An object in a function call's args? A block like if or for or while?

		}
	}
}
// ¯\_(ツ)_/¯

A semicolon disambiguates:

};

In formatted code, that's definitely closing an object or function assignment (or some other cases I can't think of atm, but it's not the other constructs listed above). Viewed one way, it may look like a sad grumbling winking face, but it's useful signal for readability, not noise. The argument that omitting the semicolon is cleaner is an aesthetic argument for increasing ambiguity, and as stated in the post's premise, ambiguity slows comprehension. TypeScript/JS is full of closing curlies, and semicolons are punctuation that reveal structure explicitly, like periods and commas in prose. If you copy this paragraph into a text editor and remove all commas and periods, you'll experience some of what I feel when reading semicolonless JS. How much does it matter? YMMV

The ambiguity argument applies to other options beyond semicolons, including:

• singleQuote: true - (differs from Prettier defaults, matches Svelte's) - largely aesthetic preference in TS/JS, but in Svelte and HTML, disambiguates from attribute "
• arrowParens: 'always' - (matches Prettier+Svelte defaults) - function args consistently get wrapped in parens
• semiColon: true - (matches Prettier+Svelte defaults) - as described above, semicolons are useful information

trailingComma is a tricky one and it has its own discussion. The Svelte codebases choose 'none', which tsv v0.2 adopted (and affirmed inheriting Svelte's choices as policy). tsv v0.1 started as 'all' (Prettier's v3+ default), and MDsveX is 'es5'.

On bracketSpacing, I personally prefer changing the Prettier default:

{ a

to false:

{a

But JS doesn't have if or block expressions (like e.g. Rust) so the lack of a space disambiguates a negligible amount compared to the other cases above in formatted code. I originally implemented tsv to my preference, but I've decided to reformat all of my code and go with the flow of the Svelte ecosystem because I can only justify it on aesthetic grounds. This feels slightly inconsistent because Prettier doesn't have the option to pad arrays, which seems to have the same aesthetic argument as bracketSpacing. tsv could improve consistency by adding spacing to arrays if the Svelte maintainers considered it desirable and worth the churn to break from Prettier.

Overall tsv tries to consistently apply the ambiguity principle in its choices. The v0.2 shift to aligning with Svelte fits well.