Zig Tiger Style

TigerStyle: Zig Coding Guidelines

Distilled from TigerBeetle's TIGER_STYLE.md. Design goal priority: Safety > Performance > Developer Experience.

1. Safety

Control Flow

• Use only simple, explicit control flow. No recursion unless provably bounded.

• Split compound conditions into nested if/else branches — ensure both the positive and negative spaces are handled or asserted.

• State invariants positively:

  // preferred
  if (index < length) { ... } else { ... }
  
  // avoid
  if (index >= length) { ... }

• Every if branch should prompt the question: does a corresponding else also need to be handled?

Assertions

Assertions detect programmer errors — not expected runtime errors. The only correct response to corrupt state is to crash. Assertions downgrade catastrophic correctness bugs into liveness bugs.

• A function must not operate blindly on data it has not checked; assert arguments at the entry point.

• Pair assertions: for any property you want to enforce, add assertions on at least two different code paths (e.g. just before writing to disk, and immediately after reading back).

• Split compound assertions:

  // preferred
  assert(a);
  assert(b);
  
  // avoid
  assert(a and b);

• Use a single-line if to assert an implication: if (a) assert(b);

• Assert relationships between compile-time constants to verify design integrity before the program even runs:

  comptime assert(@sizeOf(Header) == 128);
  comptime assert(config.pipeline_max <= config.batch_max);

• Assert both the positive space (what you expect to be true) and the negative space (what you expect to be false) — the boundary between valid and invalid is where bugs hide.

Memory

• Initialize large structs in-place via an out pointer to eliminate intermediate copies and guarantee pointer stability:

  // preferred
  fn init(target: *LargeStruct) !void {
      target.* = .{ ... };
  }
  
  // avoid
  fn init() !LargeStruct {
      return LargeStruct{ ... };
  }

Variable Scope

• Declare variables at the smallest possible scope to reduce the chance of misuse.
• Declare variables close to where they are used — do not introduce them before they are needed. This avoids POCPOU bugs (a distant cousin of TOCTOU).

Loops and Queues

• All loops and queues must have a fixed upper bound to prevent infinite loops or tail-latency spikes. Follow the fail-fast principle.
• Loops that genuinely cannot terminate (e.g. an event loop) must be explicitly asserted as such.

Error Handling

• All errors must be handled. Most catastrophic production failures stem from incorrect handling of non-fatal errors.
• Never discard error return values with _.

Other

• Use explicitly-sized integer types (u32, i64, etc.), avoid architecture-dependent usize when possible
• Enable and respect the compiler's strictest warning settings — zero tolerance for warnings.
• Do not react directly to external events inline; let the program run at its own pace (enables batching and maintains control-flow ownership).
• Keep functions as small as possible. When splitting, find semantically clean cut points:
  • Centralize all if/switch in the "parent" function; extract pure logic into helpers.
  • Let the parent own all mutable state; helpers compute what to change but don't apply it.
  • Rule of thumb: "push ifs up and fors down".

2. Performance

• Solve performance in the design phase — the biggest wins (1000x) come from architecture, not post-hoc profiling.

• Do back-of-the-envelope sketches across the four resources (network, disk, memory, CPU) and their two characteristics (bandwidth, latency).

• Optimize slowest resources first: network → disk → memory → CPU, weighted by access frequency.

• Batching is the primary tool: amortize network, disk, memory, and CPU costs.

• Distinguish control plane from data plane; batching lets both coexist safely and fast.

• Extract hot-path loops into standalone functions with primitive arguments (no self) so the compiler can cache fields in registers and humans can spot redundant work:

  // hot loop extracted, no self
  fn process_batch(items: []const Item, result: []Output) void { ... }

• Be explicit. Do not rely on the compiler to do the right thing.

• Always pass options explicitly at library call sites — never rely on defaults:

  // preferred
  @prefetch(a, .{ .cache = .data, .rw = .read, .locality = 3 });
  
  // avoid
  @prefetch(a, .{});