Turf Style Guide

What a style guide is

Think of a classroom where everyone keeps notes in the same way: the date in the top corner, headings underlined, one idea per line. None of that changes what the notes say. It means you can pick up a friend’s notebook and find your way around it at once.

A style guide does the same for code. The compiler does not care whether you indent with two spaces or eight, or whether a function is called TotalPrice or total_price. People do. Code is read many more times than it is written, and most of those reads are by someone who did not write it, including you, six months later.

Here is one program written twice. Both compile and both print 12.

fn area(width: int, height: int): int {    return width * height;}fn main(): int {    immut w: int = 3;    immut h: int = 4;    printline(area(w, h));    return 0;}

fn AREA(W:int,H:int):int{return W*H;}fn main():int{immut a:int=3;immut B:int=4;printline(AREA(a,B));return 0;}

The second one works. It is just tiring to read, and every reader pays that cost again.

Three documents, three jobs

Turf has three kinds of official writing. It helps to know which one answers which question.

• What is allowedLanguage reference →

  What a program means and what the compiler accepts. Break it and the program does not compile.

• How to write it wellStyle guide

  This guide. How readable, idiomatic Turf is written. Break it and the program still works.

• How Turf changesDesign proposals →

  How a new feature is proposed, argued over and accepted, and why.

How to read a rule

Every rule in the guide has the same four parts:

1. A number, such as TSG-101. The number never changes and is never reused for another rule, so you can quote it in a code review, a commit message or a diagnostic and it always means the same thing.
2. A level.
   • Required means everyone follows it, and a tool will eventually check it for you.
   • Recommended means it is good advice, and you can break it when you have a reason.
3. Which tool checks it, if any. Today only turf fmt checks anything, and only four rules.
4. Two examples: one to copy (Do) and one to avoid (Don’t). Both are real programs, and both compile.

The first digit of the number tells you which page the rule is on:

Where the guide is going

The guide is new. It is written now, it grows and settles during Turf 2.x, and at Turf 3.0 the formatter learns it.

• Until 3.0, turf fmt does not change. It keeps doing exactly the four things it does today (TSG-101 to TSG-104), so the formatter’s output stays the same across every 2.x release while the guide is still moving.
• Before 3.0, any rule can still change. No tool enforces the new rules yet, so changing one breaks nobody’s build.
• At 3.0, the formatting rules are frozen and turf fmt is updated to apply them, all at once. A project adopts them by running turf fmt --write one time.
• After 3.0, a new formatting rule lands in this guide and in turf fmt together, and a rule that changes what turf fmt outputs is listed in the release notes.

All rules at a glance

Changing the guide

The guide belongs to everyone who writes Turf. To suggest a new rule or argue against one, open an issue on turf-lang/turf-lang or comment on turf-lang#281. A good suggestion says which rule, what should change, and shows a short piece of real code where the change helps.

Rules are changed carefully, not on a timetable:

• A settled rule stays settled unless there is a strong reason to change it.
• New syntax gets its rules in the same release that ships it, never before.
• A rule that is removed keeps its number, marked as withdrawn, so old references still lead somewhere.

Changelog