Zig Comments

Comments are lines in your source code that the compiler ignores completely. They exist purely for humans — to explain what a piece of code does, why a certain decision was made, or to leave a note for your future self or teammates. Zig supports two styles of comments and one special style used to generate documentation.

Single-Line Comments

// This is a single-line comment
const speed = 100; // speed in kilometers per hour

Everything after // on the same line is a comment. The compiler reads nothing past those two slashes. Use single-line comments for short explanations placed next to or above the code they describe.

No Block Comments

Zig intentionally has no block comment syntax like C's /* ... */. The designers made this choice to keep the grammar simple and to avoid edge cases where a block comment inside a string literal causes confusion. To comment out multiple lines, prefix each line with //.

  C:                      Zig:
  /* Line one            // Line one
     Line two            // Line two
     Line three */       // Line three

Most editors handle this with a keyboard shortcut — selecting multiple lines and pressing Ctrl+/ (or Cmd+/) toggles // on each line at once.

Commenting Out Code Temporarily

const std = @import("std");

pub fn main() void {
    const x = 10;
    // const y = 20;          // disabled: not needed yet
    // std.debug.print("{d}\n", .{y});
    std.debug.print("x = {d}\n", .{x});
}

Commenting out code during debugging or development is common. Remove the comments once you have settled on the final code — leftover commented-out code confuses future readers.

Doc Comments

Doc comments start with /// (three slashes). They attach to the declaration that immediately follows them and are used to generate documentation automatically.

/// Calculates the area of a circle given its radius.
/// The radius must be a positive number.
/// Returns the area as a 64-bit float.
fn circleArea(radius: f64) f64 {
    return std.math.pi * radius * radius;
}

  ///  ← doc comment: attached to the next declaration
  //   ← regular comment: not attached to anything

Doc comments appear in generated API documentation and in editor tooltips when you hover over a function call. Write them as complete sentences describing what the function does, what its parameters mean, and what it returns.

Top-Level Doc Comments

A comment starting with //! documents the entire file or module rather than a single declaration. Place these at the very top of a file:

//! This module provides mathematical utility functions
//! for geometry calculations. All functions assume
//! standard Euclidean space.

const std = @import("std");

/// Returns the hypotenuse of a right triangle.
fn hypotenuse(a: f64, b: f64) f64 {
    return std.math.sqrt(a * a + b * b);
}

  File structure:
  ┌────────────────────────────────────┐
  │ //! Module-level doc comment       │ ← describes the file
  │                                    │
  │ /// Function doc comment           │ ← describes circleArea
  │ fn circleArea(...) { ... }         │
  │                                    │
  │ // Regular comment                 │ ← internal note, not in docs
  │ const INTERNAL = 42;               │
  └────────────────────────────────────┘

Writing Useful Comments

Explain Why, Not What

Code already shows what it does — a good comment explains why the decision was made:

  Bad comment (states the obvious):
  // Add 1 to counter
  counter += 1;

  Good comment (explains the reason):
  // Offset by 1 because the API uses 1-based indexing
  counter += 1;

Mark Known Limitations

// TODO: handle Unicode characters above U+FFFF
fn countChars(s: []const u8) usize {
    return s.len; // approximation: counts bytes, not code points
}

Document Non-Obvious Constraints

/// Parses an IP address string in dotted-decimal form.
/// The input slice must remain valid for the lifetime of the result —
/// the returned fields point into the original slice.
fn parseIp(raw: []const u8) IpAddress { ... }

Comment Style Conventions

  ✓ Start comments with a capital letter
  ✓ End doc comments with a period
  ✓ Place a space after //
  ✓ Keep comments short — one or two sentences
  ✗ Do not state what the next line obviously does
  ✗ Do not leave commented-out dead code in final files
  ✗ Do not use comments to patch up confusing code — rewrite the code

Practical Example: Documented Math Module

//! Geometry utilities for 2D shapes.
//! All measurements use the same unit (caller chooses meters, pixels, etc.).

const std = @import("std");

/// Returns the area of a rectangle.
pub fn rectArea(width: f64, height: f64) f64 {
    return width * height;
}

/// Returns the perimeter of a rectangle.
pub fn rectPerimeter(width: f64, height: f64) f64 {
    return 2.0 * (width + height);
}

/// Returns the area of a circle.
/// Uses the standard formula: π × r².
pub fn circleArea(radius: f64) f64 {
    return std.math.pi * radius * radius;
}

// Internal helper — not exported, no doc comment needed
fn clampPositive(val: f64) f64 {
    return if (val < 0) 0 else val;
}

Notice that public functions have /// doc comments, and the internal helper uses a plain // comment. This pattern keeps the public API well-documented while avoiding noise in the documentation output for functions that users should not call directly.