Zig Best Practices

Zig Best Practices

Follows type-first, functional, and error handling patterns from CLAUDE.md. This skill covers Zig-specific idioms only.

Type System Patterns

Tagged unions for mutually exclusive states — prevents invalid combinations that a struct with multiple nullable fields would allow:

const RequestState = union(enum) {
    idle,
    loading,
    success: []const u8,
    failure: anyerror,
};

Explicit error sets — documents exactly what can fail; anyerror hides failure modes:

const ParseError = error{ InvalidSyntax, UnexpectedToken, EndOfInput };
fn parse(input: []const u8) ParseError!Ast { ... }

Distinct types for domain IDs — compiler prevents mixing up different ID types:

const UserId = enum(u64) { _ };
const OrderId = enum(u64) { _ };

Comptime validation — catch invalid configurations at compile time, not runtime:

fn Buffer(comptime size: usize) type {
    if (size == 0) @compileError("buffer size must be greater than 0");
    return struct { data: [size]u8 = undefined, len: usize = 0 };
}

Memory Management

• Pass allocators explicitly to every function that allocates; no global allocator state.
• Place defer resource.deinit() immediately after acquisition — keeps cleanup co-located with creation.
• Use errdefer for cleanup on error paths; defer for unconditional cleanup.
• Use arena allocators for batch/temporary work; they free everything at once.
• Use std.testing.allocator in tests — reports leaks with stack traces.

fn createResource(allocator: std.mem.Allocator) !*Resource {
    const resource = try allocator.create(Resource);
    errdefer allocator.destroy(resource);  // runs only on error
    resource.* = try initializeResource();
    return resource;
}

Key Conventions

• Prefer const over var; prefer slices over raw pointers.
• Prefer comptime T: type over anytype; explicit types produce clearer errors. Use anytype only for genuinely polymorphic cases (callbacks, std.debug.print-style).
• Exhaustive switch: include an else returning an error or unreachable for truly impossible cases.
• Use std.log.scoped(.module_name) for namespaced logging; define a module-level const log constant.
• Larger cohesive files are idiomatic — tests alongside implementation, comptime generics at file scope.

Advanced Topics

• Generic containers (queues, stacks, trees): See GENERICS.md
• C library interop (raylib, SDL, curl): See C-INTEROP.md
• Debugging memory leaks (GPA, stack traces): See DEBUGGING.md

Tooling

zigdoc — browse std library and dependency docs:

zigdoc std.mem.Allocator   # std lib symbol
zigdoc vaxis.Window        # project dependency
zigdoc @init               # create AGENTS.md with API patterns

ziglint — static analysis with .ziglint.zon config:

ziglint                    # lint current directory
ziglint --ignore Z001      # suppress specific rule

References

• Language Reference: https://ziglang.org/documentation/0.15.2/
• Standard Library: https://ziglang.org/documentation/0.15.2/std/
• Zig Guide: https://zig.guide/

C Interoperability in Zig

Zig can directly import C headers, call C functions, and expose Zig functions to C. Use these patterns when integrating with existing C libraries or system APIs.

When to Use

• Wrapping C libraries (raylib, SDL, curl)
• Calling platform-specific system APIs
• Passing callbacks to C code
• Writing Zig libraries callable from C

Importing C Headers

Use @cImport to import C headers directly:

const ray = @cImport({
    @cInclude("raylib.h");
});

pub fn main() void {
    ray.InitWindow(800, 450, "window title");
    defer ray.CloseWindow();

    ray.SetTargetFPS(60);
    while (!ray.WindowShouldClose()) {
        ray.BeginDrawing();
        defer ray.EndDrawing();
        ray.ClearBackground(ray.RAYWHITE);
    }
}

Configure include paths in build.zig:

exe.addIncludePath(.{ .cwd_relative = "/usr/local/include" });
exe.linkSystemLibrary("raylib");

Extern Functions (System APIs)

Call platform APIs without bindings using extern:

const win = @import("std").os.windows;

extern "user32" fn MessageBoxA(
    ?win.HWND,
    [*:0]const u8,
    [*:0]const u8,
    u32,
) callconv(.winapi) i32;

C Callbacks

Pass Zig functions to C libraries using callconv(.C):

fn writeCallback(
    data: *anyopaque,
    size: c_uint,
    nmemb: c_uint,
    user_data: *anyopaque,
) callconv(.C) c_uint {
    const buffer: *std.ArrayList(u8) = @alignCast(@ptrCast(user_data));
    const typed_data: [*]u8 = @ptrCast(data);
    buffer.appendSlice(typed_data[0 .. nmemb * size]) catch return 0;
    return nmemb * size;
}

Key points:

• callconv(.C) makes the function callable from C
• *anyopaque is Zig's equivalent of void*
• Use @alignCast and @ptrCast to recover typed pointers
• Return 0 on error (C convention) since Zig errors can't cross FFI boundary

C Types Mapping

Debugging Memory in Zig

Use GeneralPurposeAllocator (GPA) to detect memory leaks with stack traces showing allocation origins.

When to Use

• Debugging memory leaks in development
• Validating cleanup logic in complex systems
• Investigating use-after-free or double-free bugs

GeneralPurposeAllocator Pattern

const std = @import("std");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer std.debug.assert(gpa.deinit() == .ok);
    const allocator = gpa.allocator();

    // Use allocator for all allocations
    const data = try allocator.alloc(u8, 1024);
    defer allocator.free(data);

    // Any leaked allocations will be reported at deinit
}

Configuration Options

var gpa = std.heap.GeneralPurposeAllocator(.{
    .stack_trace_depth = 10,  // Stack frames to capture (default: 8)
    .enable_memory_limit = true,
    .requested_memory_limit = 1024 * 1024,  // 1MB limit
}){};

Leak Report Output

When leaks occur, GPA prints:

error: memory leak detected
Leak at 0x7f... (1024 bytes)
    src/main.zig:42:25
    src/main.zig:38:18
    ...

Testing with Leak Detection

std.testing.allocator wraps GPA and fails tests on leaks:

test "no memory leaks" {
    const allocator = std.testing.allocator;
    var list: std.ArrayListUnmanaged(u32) = .empty;
    defer list.deinit(allocator);

    try list.append(allocator, 42);
    // Test fails if list.deinit is missing
}

Production vs Debug

• Use GPA in debug builds for safety
• Switch to std.heap.page_allocator or arena in release for performance
• std.heap.c_allocator when interfacing heavily with C code

Generic Data Structures in Zig

Use comptime type parameters to create reusable generic containers. Return a type from a function to build type-safe collections.

When to Use

• Implementing custom containers (queues, stacks, trees)
• Building type-safe wrappers around allocations
• Creating domain-specific collections

Pattern: Type-Returning Function

pub fn Queue(comptime Child: type) type {
    return struct {
        const Self = @This();
        const Node = struct {
            data: Child,
            next: ?*Node,
        };

        allocator: std.mem.Allocator,
        start: ?*Node,
        end: ?*Node,

        pub fn init(allocator: std.mem.Allocator) Self {
            return Self{ .allocator = allocator, .start = null, .end = null };
        }

        pub fn enqueue(self: *Self, value: Child) !void {
            const node = try self.allocator.create(Node);
            node.* = .{ .data = value, .next = null };
            if (self.end) |end| end.next = node else self.start = node;
            self.end = node;
        }

        pub fn dequeue(self: *Self) ?Child {
            const start = self.start orelse return null;
            defer self.allocator.destroy(start);
            if (start.next) |next| self.start = next else {
                self.start = null;
                self.end = null;
            }
            return start.data;
        }
    };
}

Key Techniques

• @This() returns the enclosing struct type for self-reference
• Nested Node struct keeps implementation details private
• Allocator passed to init, stored for later operations
• defer for cleanup in dequeue prevents leaks

Usage

var queue = Queue(u32).init(allocator);
try queue.enqueue(42);
const value = queue.dequeue(); // ?u32