Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Sorting

Sort your code alphabetically unless you have a documented reason not to.

Article: Sorting

Every developer has a system for where a field goes. The system lives in their head, conflicts with everyone else’s, and is invisible to the next person. Six developers later the struct is sediment: layers, each one a person who did not want to argue. Alphabetical order needs no documentation, no politics and no archaeology. You do not scan; you binary-search.

These seven rules are the formatter half of rabot. rabot fmt rewrites all of them in place; rabot check reports them.

What is sorted, and how

Order is case-insensitive and natural, so field2 comes before field10. Comments before a member move with it. Whitespace stays where it is, so a single-line list stays single-line.

Groups

Alphabetical order removes the invisible system: the one in a developer’s head that nobody else can read. Grouping related fields is not that system, as long as the grouping is visible. A blank line makes it visible:

#![allow(unused)]
fn main() {
struct Person {
    // Name
    first_name: String,
    last_name: String,

    // Address
    city: String,
    street: String,
}
}

A blank line splits fields, variants, struct literals and struct patterns into groups, and rabot sorts each group on its own. Nothing moves across a blank line. A comment at the top of a group is the group’s heading and stays there; any other comment moves with the member below it. To document the first field of a group rather than head the group, use a doc comment (///), which belongs to the field.

Two things are not groups:

  • A list where every member is set apart by a blank line. That is spacing (a blank line between each documented field, say), and the list is sorted as a whole. Otherwise the style alone would switch the rule off.
  • Impl and trait items. A blank line between every method is the norm there, so they are always sorted as a whole.

Alphabetical order still applies inside a group, so start, end or x, y, z in one group are reported. When their order matters, they are often a type waiting to be named (Range, Point); when not, write the reason down.

What is left alone

Lists whose order is behaviour are never touched, and need no comment:

WhatWhy the order matters
#[repr(..)] typesthe memory layout follows declaration order
types deriving PartialOrd or Ordcomparison goes field by field, variant by variant, in declaration order
enums with explicit discriminants (A = 1)the numbering is the point
#[serde(untagged)] enums, or enums with an untagged variantserde tries the variants top to bottom and keeps the first that fits
types with a derive from order-sensitive-derivesby default: clap, argh and structopt (positional arguments), borsh, bincode and SCALE (Encode/Decode, positional binary encodings), strum (EnumIter, VariantArray, VariantNames), uniffi (Record, Enum, Error: foreign constructors)

Attributes inside #[cfg_attr(..)] count too: a type that derives uniffi::Record only behind a feature still keeps its order.

Struct literals whose initializers may have side effects are reported, not rewritten. Function parameters are never sorted; the article calls calling convention a real exception.

What rabot cannot see is drop order: fields are dropped top to bottom, and a guard that must outlive what it protects is a reason to write down.