zig-style-enforcer

Zig Style Enforcer

This skill ensures code follows Zig conventions and idioms for consistency and readability.

Naming Conventions

Functions and Variables: snake_case

// GOOD
pub fn parseConfigFile(path: []const u8) !Config { }
const max_stack_size = 1024;
var instruction_pointer: usize = 0;

// BAD
pub fn ParseConfigFile(path: []const u8) !Config { }  // PascalCase
const MaxStackSize = 1024;  // PascalCase
var instructionPointer: usize = 0;  // camelCase

Types and Namespaces: PascalCase

// GOOD
pub const Server = struct { };
pub const ConfigFile = struct { };
pub const ValueType = enum { };

// BAD
pub const server = struct { };  // lowercase
pub const config_file = struct { };  // snake_case
pub const value_type = enum { };  // snake_case

Constants: Depends on Context

// Module-level constants use snake_case
const default_stack_size = 1024;
const max_name_length = 255;

// Enum values use snake_case
pub const Opcode = enum {
    label,
    func_info,
    call,
    call_last,
};

// Compile-time parameters use PascalCase
pub fn List(comptime T: type) type {
    return struct { };
}

Private vs Public

pub const Server = struct {
    // Public fields
    pub allocator: Allocator,

    // Private fields (no pub)
    stack: []Value,
    registers: []Value,

    // Public methods
    pub fn init(allocator: Allocator) !Server { }
    pub fn deinit(self: *Server) void { }

    // Private methods (no pub)
    fn executeInstruction(self: *Server) !void { }
};

Code Organization

Module Structure

// 1. Standard library imports
const std = @import("std");
const Allocator = std.mem.Allocator;

// 2. Local imports
const Value = @import("value.zig").Value;
const Config = @import("config.zig").Config;

// 3. Module-level constants
const MAX_STACK_SIZE = 1024;
const DEFAULT_REGISTERS = 256;

// 4. Error sets
pub const ServerError = error{
    StackOverflow,
    InvalidOpcode,
};

// 5. Type definitions
pub const Server = struct {
    // ...
};

// 6. Public functions
pub fn execute(server: *Server) !void {
    // ...
}

// 7. Private helper functions
fn validateOpcode(op: u8) bool {
    // ...
}

// 8. Tests
test "Server initialization" {
    // ...
}

File Naming

// GOOD: snake_case for files
server.zig
config_parser.zig
value_list.zig

// BAD
Server.zig  // PascalCase
configParser.zig  // camelCase

Zig Idioms

Use const by Default

// GOOD: const for immutable
const allocator = std.heap.page_allocator;
const file_path = "config.json";

// BAD: var when const would work
var allocator = std.heap.page_allocator;

// GOOD: var only when needed
var counter: usize = 0;
counter += 1;  // Mutated, so var is correct

Use defer for Cleanup

// GOOD: defer immediately after allocation
const buffer = try allocator.alloc(u8, 1024);
defer allocator.free(buffer);

var file = try std.fs.cwd().openFile(path, .{});
defer file.close();

// BAD: defer far from allocation
const buffer = try allocator.alloc(u8, 1024);
// ... lots of code ...
defer allocator.free(buffer);  // Easy to miss

Use errdefer for Error Cleanup

pub fn init(allocator: Allocator) !Server {
    const stack = try allocator.alloc(Value, 1024);
    errdefer allocator.free(stack);

    const registers = try allocator.alloc(Value, 256);
    errdefer allocator.free(registers);

    return Server{
        .stack = stack,
        .registers = registers,
    };
}

Prefer Slices Over Pointers

// GOOD: Slices include length
pub fn process(data: []const u8) !void {
    if (data.len < 4) return error.BufferTooSmall;
    // ...
}

// BAD: Raw pointers lose size info
pub fn process(data: [*]const u8, len: usize) !void {
    if (len < 4) return error.BufferTooSmall;
    // ...
}

Use Tagged Unions

pub const Value = union(enum) {
    small_int: i32,
    big_int: *BigInt,
    float: f64,
    string: []const u8,
    list: *ListValue,
    map: *MapValue,

    pub fn deinit(self: Value) void {
        switch (self) {
            .small_int, .float => {},  // No cleanup
            .big_int => |bi| bi.deinit(),
            .string => |s| s.deinit(),
            .list => |l| l.deinit(),
            .map => |m| m.deinit(),
        }
    }
};

Use Comptime for Generic Code

pub fn ArrayList(comptime T: type) type {
    return struct {
        items: []T,
        allocator: Allocator,

        pub fn init(allocator: Allocator) ArrayList(T) {
            return .{
                .items = &[_]T{},
                .allocator = allocator,
            };
        }
    };
}

Prefer Error Unions Over Optionals for Failures

// GOOD: Error union provides context
pub fn divide(a: i32, b: i32) !i32 {
    if (b == 0) return error.DivisionByZero;
    return @divTrunc(a, b);
}

// LESS GOOD: Optional loses error info
pub fn divide(a: i32, b: i32) ?i32 {
    if (b == 0) return null;  // Why did it fail?
    return @divTrunc(a, b);
}

Use Explicit Field Initialization

// GOOD: Explicit field names
return Server{
    .allocator = allocator,
    .stack = stack,
    .registers = registers,
    .ip = 0,
    .sp = 0,
};

Code Style

Indentation and Spacing

• 4 spaces for indentation
• Blank line between functions
• No trailing whitespace

Line Length

// GOOD: Keep lines under 100 characters
const result = try processConfigFile(
    allocator,
    file_path,
    .{ .validate = true, .debug = false },
);

Comments

// GOOD: Doc comments for public API
/// Executes the next instruction.
///
/// Returns ServerError if execution fails.
pub fn execute(self: *Server) ServerError!void {
    // TODO: Add support for tail call optimization
}

// BAD: Useless comments
// This function executes
pub fn execute(self: *Server) !void { }

Switch Statements

// GOOD: Exhaustive switches
switch (value) {
    .small_int => |i| std.debug.print("{d}", .{i}),
    .float => |f| std.debug.print("{d}", .{f}),
    .string => |s| std.debug.print("{s}", .{s}),
    .list => |l| printList(l),
    .map => |m| printMap(m),
}

// GOOD: Use else for catch-all if needed
switch (opcode) {
    .call, .call_last => try self.executeCall(),
    .ret => try self.executeReturn(),
    else => return error.InvalidOpcode,
}

Error Handling

// GOOD: Propagate errors
pub fn run(self: *Server) !void {
    try self.execute();
    try self.validate();
}

// GOOD: Handle specific errors
pub fn run(self: *Server) void {
    self.execute() catch |err| switch (err) {
        error.StackOverflow => self.handleOverflow(),
        error.InvalidOpcode => self.handleInvalidOp(),
        else => {
            std.log.err("Unexpected error: {}", .{err});
            return;
        },
    };
}

// BAD: Silent error swallowing
pub fn run(self: *Server) void {
    self.execute() catch {};  // Errors ignored!
}

Anti-Patterns to Avoid

Don't Use Hungarian Notation

// BAD
const pBuffer: *u8 = undefined;
const nCount: usize = 0;

// GOOD
const buffer: *u8 = undefined;
const count: usize = 0;

Don't Mix Styles

// BAD: Inconsistent naming
pub const Server_State = struct {
    currentIP: usize,
    stack_pointer: usize,
};

// GOOD: Consistent naming
pub const ServerState = struct {
    current_ip: usize,
    stack_pointer: usize,
};

Don't Over-Comment

// BAD: Comments state the obvious
// Increment the counter
counter += 1;

// GOOD: Comments explain why
// Skip null terminators in name table
if (byte == 0) continue;

Don't Use Global State

// BAD: Global mutable state
var global_server: Server = undefined;

pub fn execute() void {
    global_server.run();
}

// GOOD: Pass state explicitly
pub fn execute(server: *Server) void {
    server.run();
}

Style Checklist

When writing code:

• Functions and variables use snake_case
• Types use PascalCase
• Use const by default, var only when mutating
• defer immediately after allocation
• Prefer slices over raw pointers
• Use tagged unions for variants
• Explicit field initialization
• Doc comments on public API
• Exhaustive switch statements
• Lines under 100 characters
• No trailing whitespace

When reviewing code:

• Naming consistent with conventions
• Cleanup properly structured with defer
• Error handling explicit, not silent
• Comments add value, not noise
• Code formatted consistently
• Tests descriptive and comprehensive

Formatting

Use zig fmt to automatically format code:

# Format a single file
zig fmt src/server.zig

# Format entire project
zig fmt src/

Always run zig fmt before committing code.