Bun Zig style guide

Note: This style guide is a work-in-progress. Additional sections will be added, and existing sections may be modified.

Naming
- Variables, parameters, and fields should be snake_case
- Functions should be camelCase
- Non-namespace types should be TitleCase
- Type aliases are always TitleCase
- File namespaces should be snake_case.zig
- File structs should be TitleCase.zig
- Acronyms and initialisms are treated as normal words
- Method receiver should always be named self
- Don’t repeat @This()
- Always bind @This() to Self or the name of the type
- Method receiver type should not be qualified
- Private fields should start with #
- Internal fields should start with _
- Named blocks with no nested named blocks should be called blk:
- Do not prefix variables with _ to avoid name conflicts
- Use descriptive names
- Avoid excessively long names
- Avoid redundancy in names
- Semantically different things must have semantically different names
Formatting
- Limit lines to 100 characters
- Use blank lines sparingly
- Avoid Struct{} syntax; use struct literals
- Prefer decl literals to Struct.init() syntax
- Prefer type coercion without @as casts
- Avoid useless blocks
- Keep related items together
- Init functions should be at the top of the container
- deinit should immediately follow init functions
- Do not label blocks or loops unnecessarily
- Do not use orelse unreachable
- Avoid unnecessary uses of var
- Prefer positive conditions in if-else statements
File organization & imports
- A file’s children should live in a sibling directory of the same name
- Access items from bun instead of importing them directly
- Don’t import from subdirectories, except immediate children
- Imports containing .. must not descend into a subdirectory
- Imports should not change the name of the imported item
- Do not split files into tightly coupled pieces
Reducing nesting
- Avoid if-else statements containing a break in control flow
- Avoid if statements that both contain and are followed by a break
- Avoid nested if statements where an else if chain would suffice
- Avoid nested if statements where an and expression would suffice
- else blocks should not contain a single if statement
- Avoid large nested type definitions
- Avoid inline type definitions
- Avoid deeply nested boolean expressions
- Avoid large blocks in functions
Reducing potential IB
- Avoid unwrapping an optional after checking for null
- Avoid tagged union field accesses after checking active field
- Avoid @intCast after a manual range check
- Minimize use of untagged unions
- Avoid storing a pointer and length separately
- Avoid repeating the same potential-IB operation
- Avoid splitting a switch into disjoint pieces
- Try to avoid @fieldParentPtr
- Avoid self-references
Errors
- Avoid inferred error sets in public functions
- Give names to large or repeatedly used error sets
- Avoid anyerror
- catch expressions must capture the error
- catch expressions should not ignore the error
- Do not use handleOom in a function that could return error.OutOfMemory
- Avoid excessive uses of handleOom
Functions
- Do not use bool parameters
- Do not use inline fn unless semantic inlining is required
- Functions should not take a large number of parameters
- Avoid writing huge functions
- Avoid unused parameters
- Avoid out-parameters
- Explicitly mark comptime conditions
Declaration visibility
- Avoid pub imports
- Avoid making functions unnecessarily pub
- Methods in private types should be pub if part of the type’s public API
Invariants
- Background
- Invariants always hold for all instances of a given type
- Methods should avoid making assumptions not guaranteed by invariants
- Methods must uphold all invariants
- Public fields cannot break invariants if set to an arbitrary value
- Avoid long or complex lists of invariants
- Working with builtin & standard library types
Lifecycle
Ownership
Preconditions & postconditions
Thread safety
Atomics
DRY (don’t repeat yourself)
Smart pointers
Monomorphized generic allocators
Runtime safety checks
Efficiency
Global variables
Metaprogramming

Naming

Variables, parameters, and fields should be `snake_case`

The names of variables, parameters, and struct/enum/union fields should be snake_case.

✅️ Correct:

const max_compression_level: usize = 100;
const File = struct {
    cache_index: usize,
    decoded_contents: []const u8,
    pub fn compress(self: *File, compression_level: u32) void { ... }
}

❌️ Incorrect:

const MAX_COMPRESSION_LEVEL: usize = 100; // SCREAMING_SNAKE_CASE not allowed
const File = struct {
    cacheIndex: usize, // fields should not be camelCase
    decodedContents: []const u8,
    pub fn compress(self: *File, compressionLevel: u32) void { ... }
    // parameters should not be camelCase ^
};

Justification: Compliance with Zig’s style guide.

Exception: Variables, parameters, and fields of type type should be TitleCase instead.

Exception: It may be necessary to use non-compliant names when writing raw bindings to foreign code, like a C library that exposes variables with such names. Any abstractions built on top of the raw bindings should use compliant names, however.

Functions should be `camelCase`

The names of functions (including methods) should be camelCase.

✅️ Correct:

pub fn appendSlice(comptime T: type, list: *List(T), slice: []const T) !void {
    for (slice) |*item| {
        try list.pushCloned(item);
    }
}

❌️ Incorrect:

pub fn append_slice(comptime T: type, list: *List(T), slice: []const T) !void {
    // ^ functions should not be snake_case
    for (slice) |*item| {
        try list.push_cloned(item); // methods should not be snake_case
    }
}

Justification: Compliance with Zig’s style guide.

Exception: Functions that return a type should be TitleCase instead.

Non-namespace types should be `TitleCase`

Non-namespace structs, unions, enums, and opaques should be TitleCase.

If a struct has no members and is not instantiated, it is a namespace and should be snake_case.

✅️ Correct:

const network = struct {
    pub const Connection = struct { ... };
    pub const Protocol = enum { tcp, udp };
};

❌️ Incorrect:

const Network = struct { // namespace should be snake_case
    pub const connection = struct { ... }; // struct should be TitleCase
    pub const PROTOCOL = enum { tcp, udp }; // enum should be TitleCase
};

Justification: Compliance with Zig’s style guide.

Type aliases are always `TitleCase`

All variables of type type should be TitleCase, even if they’re aliases of primitive types.

✅️ Correct:

const Length = usize;
const ByteString = []const u8;
const CpuTemp = f32;

❌️ Incorrect:

const length = usize;
const bytestring = []const u8;
const cpu_temp = f32;

Justification: Compliance with Zig’s style guide.

File namespaces should be `snake_case.zig`

Files that do not have any top-level fields and are not instantiated are namespaces, and should have names that consist of a snake_case identifier, plus a .zig extension.