| name | kelley-zig-philosophy |
| description | Write Zig code in the style of Andrew Kelley, creator of Zig. Emphasizes simplicity, explicit behavior, compile-time metaprogramming, and being a better C. Use when writing systems code that prioritizes clarity and safety. |
| tags | zig, comptime, allocators, manual-memory, simplicity, explicit, no-hidden-control-flow, systems, safety |
Andrew Kelley Style Guide
Overview
Andrew Kelley created Zig to address the shortcomings of C and C++ while maintaining their strengths. His philosophy centers on simplicity, explicitness, and leveraging compile-time computation to eliminate runtime overhead.
Core Philosophy
"Zig is not trying to be Rust. Zig is trying to be a better C."
"The language should not have hidden control flow."
"Communicate intent to the compiler and other programmers."
Kelley believes that complexity should be explicit and visible, not hidden behind abstractions that obscure what the code actually does.
Design Principles
-
No Hidden Control Flow: What you see is what executes.
-
No Hidden Allocations: Memory operations are explicit.
-
Compile-Time Over Runtime: Move computation to compile time.
-
Simplicity Over Features: Small, orthogonal feature set.
When Writing Code
Always
- Use
comptime to eliminate runtime overhead
- Make allocations explicit with allocator parameters
- Handle all error cases explicitly
- Prefer slices over pointers when possible
- Use
defer for cleanup
- Document with
/// doc comments
Never
- Hide control flow in operator overloads (Zig doesn't have them)
- Allocate implicitly—always pass allocators
- Ignore errors—handle or explicitly discard
- Use C-style null-terminated strings when slices work
- Rely on undefined behavior
Prefer
comptime over runtime generics- Error unions over exceptions
- Slices over raw pointers
defer over manual cleanup- Explicit allocators over global state
- Packed structs for binary compatibility
Code Patterns
Compile-Time Computation
// comptime: evaluated at compile time, zero runtime cost
fn fibonacci(comptime n: u32) u32 {
if (n <= 1) return n;
return fibonacci(n - 1) + fibonacci(n - 2);
}
// This is computed at compile time
const fib_10 = fibonacci(10); // 55, no runtime computation
// Generic programming with comptime
fn max(comptime T: type, a: T, b: T) T {
return if (a > b) a else b;
}
const result = max(i32, 5, 10); // Type-safe, zero overhead
// Compile-time type reflection
fn printFields(comptime T: type) void {
const fields = @typeInfo(T).Struct.fields;
inline for (fields) |field| {
@compileLog(field.name);
}
}
Error Handling
// Errors are values, not exceptions
const FileError = error{
NotFound,
PermissionDenied,
Unexpected,
};
fn readFile(path: []const u8) FileError![]u8 {
// Return error or success
if (path.len == 0) {
return error.NotFound;
}
// ... read file
return data;
}
// Caller must handle errors explicitly
pub fn main() void {
const data = readFile("config.txt") catch |err| {
switch (err) {
error.NotFound => std.debug.print("File not found\n", .{}),
error.PermissionDenied => std.debug.print("Access denied\n", .{}),
else => std.debug.print("Unexpected error\n", .{}),
}
return;
};
// Use data...
}
// try: shorthand for catch and return
fn processFile(path: []const u8) !void {
const data = try readFile(path); // Propagates error if any
// Process data...
}
// errdefer: cleanup only on error
fn allocateAndProcess(allocator: Allocator) !*Resource {
const resource = try allocator.create(Resource);
errdefer allocator.destroy(resource); // Only runs if error occurs
try resource.init(); // If this fails, resource is freed
return resource;
}
Explicit Memory Management
const std = @import("std");
const Allocator = std.mem.Allocator;
// Always pass allocator explicitly
fn createBuffer(allocator: Allocator, size: usize) ![]u8 {
return allocator.alloc(u8, size);
}
fn processData(allocator: Allocator, input: []const u8) ![]u8 {
var result = try allocator.alloc(u8, input.len * 2);
errdefer allocator.free(result);
// Process...
return result;
}
pub fn main() !void {
// Choose your allocator
var gpa = std.heap.GeneralPurposeAllocator(.{}){};
defer _ = gpa.deinit();
const allocator = gpa.allocator();
const buffer = try createBuffer(allocator, 1024);
defer allocator.free(buffer);
// Use buffer...
}
Defer and Cleanup
fn processFile(path: []const u8) !void {
const file = try std.fs.cwd().openFile(path, .{});
defer file.close(); // Always closes, even on error
var buffer: [4096]u8 = undefined;
const bytes_read = try file.read(&buffer);
// Process buffer...
}
// Multiple defers execute in reverse order
fn complexOperation() !void {
const a = try acquireResourceA();
defer releaseResourceA(a);
const b = try acquireResourceB();
defer releaseResourceB(b);
const c = try acquireResourceC();
defer releaseResourceC(c);
// On exit (success or error):
// 1. releaseResourceC
// 2. releaseResourceB
// 3. releaseResourceA
}
Slices Over Pointers
// Slices: pointer + length, safer than raw pointers
fn processBytes(data: []const u8) void {
for (data) |byte| {
// Safe iteration, bounds checked in debug
std.debug.print("{x}", .{byte});
}
}
// Slice operations
fn example() void {
const array = [_]u8{ 1, 2, 3, 4, 5 };
const slice = array[1..4]; // [2, 3, 4]
const from_start = array[0..3]; // [1, 2, 3]
const to_end = array[2..]; // [3, 4, 5]
// Sentinel-terminated slices for C interop
const c_string: [:0]const u8 = "hello";
}
// Convert between pointer types explicitly
fn pointerConversions(ptr: [*]u8, len: usize) void {
const slice = ptr[0..len]; // Many-pointer to slice
const single = &ptr[0]; // Many-pointer to single pointer
}
Structs and Methods
const Point = struct {
x: f32,
y: f32,
// Methods are just namespaced functions
pub fn distance(self: Point, other: Point) f32 {
const dx = self.x - other.x;
const dy = self.y - other.y;
return @sqrt(dx * dx + dy * dy);
}
pub fn zero() Point {
return .{ .x = 0, .y = 0 };
}
};
// Usage
const p1 = Point{ .x = 0, .y = 0 };
const p2 = Point{ .x = 3, .y = 4 };
const dist = p1.distance(p2); // 5.0
const origin = Point.zero();
Optionals and Null Safety
// Optional: T or null, explicit handling required
fn findUser(id: u32) ?User {
if (id == 0) return null;
return users[id];
}
pub fn main() void {
// Must handle null case
if (findUser(42)) |user| {
std.debug.print("Found: {s}\n", .{user.name});
} else {
std.debug.print("User not found\n", .{});
}
// orelse: provide default
const user = findUser(42) orelse User.anonymous();
// .?: unwrap or undefined behavior (debug trap)
const user = findUser(42).?; // Crashes if null in debug
}
Mental Model
Kelley approaches systems programming by asking:
- Can this run at compile time? Use
comptime to shift work
- Is control flow visible? No hidden jumps or allocations
- Are errors handled? Every error path must be addressed
- Is memory explicit? Allocators passed, lifetimes clear
- Would a C programmer understand the output? Zig maps to predictable machine code
Signature Kelley Moves
comptime for zero-cost generics- Explicit allocator parameters everywhere
defer/errdefer for cleanup- Error unions instead of exceptions
- Slices instead of pointer arithmetic
- No operator overloading, no hidden behavior
