Agent Skills: Idiomatic Zig Programming

Idiomatic Zig Programming

Expert guidance for writing idiomatic Zig code that embodies the Zen of Zig: explicit intent, no hidden control flow, and compile-time over runtime.

Prefer Zig 0.16.0 idioms: std.Io with explicit io, main(init: std.process.Init|Minimal) for args/env, destructuring, labeled switch, @branchHint on hot paths, .empty for std containers, DebugAllocator in debug builds, and explicit backing integers for packed types.

Zen of Zig

| Principle | Implication | |-----------|-------------| | Communicate intent precisely | APIs should make ownership, failure, and allocation obvious | | Edge cases matter | Handle invalid states explicitly rather than hoping they never happen | | Favor reading over writing | Prefer straightforward code over abstraction tricks | | Compile errors > runtime crashes | Push invariants into types and comptime checks | | Runtime crashes > silent bugs | Fail loudly rather than corrupting state | | Memory is a resource | Accept allocators explicitly; define ownership clearly | | No hidden control flow | No exceptions, GC, implicit allocations, or magical globals |

Workflow Decision Tree

1. Need mutation? Use var; otherwise use const.
2. Need allocation? Accept std.mem.Allocator; never hide allocation behind globals.
3. Can fail? Return !T and propagate with try.
4. Need cleanup? Place defer or errdefer immediately after acquisition.
5. Need OS interaction? Pass std.Io explicitly; keep side effects at the boundary.
6. Need environment variables or args? Read them in main(init) and pass explicit config downward.
7. Need generic code? Use comptime parameters and exhaustive switch.
8. Need C interop? @cImport still works, but prefer build-system-managed translate-c for new code when practical.
9. Need hot-path tuning? Measure first, then use layout/data changes and targeted @branchHint.

Essential Patterns

Error Unions

const std = @import("std");

const FileError = error{ NotFound, PermissionDenied, InvalidPath };

fn readConfig(io: std.Io, path: []const u8) FileError!Config {
    const file = std.Io.Dir.cwd().openFile(io, path, .{}) catch |err| {
        return switch (err) {
            error.FileNotFound => error.NotFound,
            error.AccessDenied => error.PermissionDenied,
            else => error.InvalidPath,
        };
    };
    defer file.close(io);

    // ... parse config
    return config;
}

Allocator Ownership

const std = @import("std");

fn processData(allocator: std.mem.Allocator, input: []const u8) ![]u8 {
    const result = try allocator.alloc(u8, input.len * 2);
    errdefer allocator.free(result);

    // ... write into result

    return result;
}

pub fn main() !void {
    var debug_alloc: std.heap.DebugAllocator(.{}) = .init;
    defer _ = debug_alloc.deinit();
    const allocator = debug_alloc.allocator();

    const data = try processData(allocator, "input");
    defer allocator.free(data);
}

Tagged Unions

const PaymentState = union(enum) {
    pending: void,
    processing: struct { transaction_id: []const u8 },
    completed: Receipt,
    failed: PaymentError,

    pub fn describe(self: PaymentState) []const u8 {
        return switch (self) {
            .pending => "Waiting for payment",
            .processing => |p| p.transaction_id,
            .completed => |r| r.summary,
            .failed => |e| e.message,
        };
    }
};

Resource Management with std.Io

const std = @import("std");

fn processFile(io: std.Io, allocator: std.mem.Allocator, path: []const u8) !void {
    const file = try std.Io.Dir.cwd().openFile(io, path, .{});
    defer file.close(io);

    const buffer = try allocator.alloc(u8, 4096);
    defer allocator.free(buffer);

    // ... read/write using file.reader(io, ...) or file.writer(io, ...)
}

Quick Reference

const std = @import("std");

// const by default
const answer: u32 = 42;
var counter: u32 = 0;

// optionals and error unions
const maybe_value: ?u32 = null;
const value = maybe_value orelse 0;

fn canFail() !u32 {
    return error.SomeError;
}
const n = try canFail();

// destructuring (0.16+)
const sum, const overflow = @addWithOverflow(a, b);

// std containers prefer .empty
var list: std.ArrayListUnmanaged(u8) = .empty;
var map: std.AutoHashMapUnmanaged(u32, u32) = .empty;

// type info uses quoted identifiers
switch (@typeInfo(T)) {
    .@"struct" => |s| _ = s,
    .@"int" => |i| _ = i,
    else => {},
}

// std.Io at the boundary
pub fn main(init: std.process.Init.Minimal) !void {
    var debug_alloc: std.heap.DebugAllocator(.{}) = .init;
    defer _ = debug_alloc.deinit();
    const allocator = debug_alloc.allocator();

    const io = std.testing.io; // use a real Io backend in non-test code
    _ = io;
    _ = allocator;
    _ = init;
}

Zig 0.16.0 Notes

std.Io Is the Default

• Prefer std.Io APIs for filesystem, networking, time, process, and synchronization boundaries.
• Io.Threaded is the stable default implementation.
• Io.Evented remains experimental; do not assume feature parity, especially around networking.

Args and Environment Belong to main(init)

• Read environment variables and CLI args in main(init: std.process.Init|Minimal).
• Pass explicit config structs, individual values, or *const std.process.Environ.Map to lower layers.
• Avoid new code that reaches for process-global environment state when explicit plumbing is possible.

const std = @import("std");

pub fn main(init: std.process.Init.Minimal) !void {
    var arena: std.heap.ArenaAllocator = .init(std.heap.page_allocator);
    defer arena.deinit();

    const port = init.environ.getPosix("PORT") orelse "8080";
    var args = init.args.iterate();
    _ = args.next(); // argv0

    try run(port);
}

New Type Construction Builtins

@Type has been replaced by specific builtins:

• @EnumLiteral()
• @Int(...)
• @Tuple(...)
• @Pointer(...)
• @Fn(...)
• @Struct(...)
• @Union(...)
• @Enum(...)

There is no @Array builtin in 0.16.0; use normal array syntax. There is no @Opaque; write opaque {} directly.

Packed Types Need Explicit Backing Integers

const Flags = packed struct(u8) {
    writable: bool = true,
    enumerable: bool = true,
    _reserved: u6 = 0,
};

Use the same explicitness for packed unions when representation matters.

Allocator Defaults

• GeneralPurposeAllocator is gone.
• Prefer DebugAllocator in debug-heavy development workflows.
• Prefer std.heap.smp_allocator or another deliberate allocator choice in release/runtime code.
• ArenaAllocator is thread-safe in 0.16.0, but still use it for lifetime grouping, not as a universal default.

Small but Useful 0.16 Changes

• Prefer .empty over old init() patterns for unmanaged std containers.
• Prefer std.mem.find* names over old indexOf* names in new code.
• @trap() is preferable to relying on unreachable when you want a defined abort in release builds.

Forbidden Patterns

| ❌ Never | ✅ Instead | |----------|-----------| | Global allocator / hidden malloc | Pass Allocator explicitly | | Hidden environment or args lookups deep in the stack | Read in main(init) and pass config explicitly | | @Type(...) or made-up @StructType/@IntType names | Use @Struct, @Int, @Enum, @Pointer, etc. | | GeneralPurposeAllocator | Use DebugAllocator, smp_allocator, arena, or another deliberate choice | | std.fs-style examples without io in 0.16-only code | Use std.Io APIs with explicit io | | packed struct or packed union without backing int when layout matters | Spell the backing integer explicitly | | Blindly enabling Io.Evented in production guidance | Treat it as experimental until validated | | var when const works | Default to const | | Ignoring errors silently | Handle with catch or propagate with try | | OOP inheritance hierarchies | Use composition and tagged unions |

Detailed References

• idioms.md - Data-oriented design, memory patterns, testing
• async-io.md - New async/Io model, futures, cancellation
• c-interop.md - C FFI, build-system integration, ABI compatibility