Comments and Documentation in Zig: A Practical Guide

Comments in Zig are text ignored by the compiler used to explain intent, context, or provide public documentation.

As in almost all languages, a good comment shouldn’t repeat what the code already says. Its job is to explain why a decision exists, what contract a function has, or what detail is worth remembering when we come back six months later.

Normal Comments //

A normal comment starts with // and extends to the end of the line.

const age = 42; // Comment at the end of a line

// We can also use a full line
const active = true;

This is useful for leaving small notes, clarifying an unusual condition, or marking a temporary decision.

// We use u16 because the protocol reserves exactly 16 bits for this field.
const code: u16 = readCode();

Notice the difference: the comment doesn’t say “we create a constant”. We already see that. The comment explains why the chosen type is u16.

Documentation Comments ///

Comments with a triple slash (///) are documentation comments. They are placed directly above a declaration: a function, a struct, a public constant, etc.

/// Calculates the area of a rectangle.
///
/// `base` and `height` must be expressed in the same unit.
pub fn areaRectangle(base: f32, height: f32) f32 {
    return base * height;
}

The idea is that this text is part of the function’s public contract. It’s not a private note for us; it’s documentation for anyone who will use that API.

That’s why it’s good to write it clearly:

• What the function does.
• What the parameters mean if it’s not obvious.
• What it returns.
• What errors it can produce, if it returns a !T.

Module Comments //!

Zig also has documentation comments for the current container, using //!.

These usually appear at the beginning of a file to explain what that module represents.

//! Basic mathematical utilities for the Zig course.
//!
//! This module contains small functions used in the examples.

const std = @import("std");

The difference is straightforward:

• /// documents the declaration that comes right after.
• //! documents the file or container where it is written.

Comments and Clean Code

There’s a common temptation when learning: to comment absolutely everything.

// Declare a variable called counter
var counter: u32 = 0;

// Add one to the counter
counter += 1;

This doesn’t add much. The code already said it, and the comment becomes noise.

However, this comment does help:

// The counter starts at 1 because the protocol reserves 0 as an invalid value.
var counter: u32 = 1;

Here the comment explains a rule external to the code. That’s worth keeping.

Comments in Public APIs

Zig places a high value on code being explicit. If a function is part of a public API, especially if it’s pub, it’s standard to document it with ///.

/// Finds a user by identifier.
///
/// Returns `null` if no user exists with that `id`.
pub fn findUser(id: u32) ?User {
    // ...
}