Comentarios y documentación en Zig: guía práctica

Los comentarios en Zig son texto ignorado por el compilador que sirve para explicar intención, contexto o documentación pública.

Como en casi todos los lenguajes, un buen comentario no debería repetir lo que el código ya dice. Su trabajo es explicar por qué existe una decisión, qué contrato tiene una función, o qué detalle conviene no olvidar cuando volvamos dentro de seis meses.

Comentarios normales //

El comentario normal empieza con // y llega hasta el final de la línea.

const edad = 42; // Comentario al final de una línea

// También podemos usar una línea completa
const activo = true;

Esto es útil para dejar notas pequeñas, aclarar una condición rara o marcar una decisión temporal.

// Usamos u16 porque el protocolo reserva exactamente 16 bits para este campo.
const codigo: u16 = leerCodigo();

Fíjate en la diferencia: el comentario no dice “creamos una constante”. Eso ya lo vemos. El comentario explica por qué el tipo elegido es u16.

Comentarios de documentación ///

Los comentarios con triple barra (///) son comentarios de documentación. Se colocan justo encima de una declaración: una función, un struct, una constante pública, etc.

/// Calcula el área de un rectángulo.
///
/// `base` y `altura` deben estar expresadas en la misma unidad.
pub fn areaRectangulo(base: f32, altura: f32) f32 {
    return base * altura;
}

La idea es que este texto forma parte del contrato público de la función. No es una nota privada para nosotros, es documentación para quien vaya a usar esa API.

Por eso conviene escribirlo con claridad:

• Qué hace la función.
• Qué significan los parámetros si no es obvio.
• Qué devuelve.
• Qué errores puede producir, si devuelve un !T.

Comentarios de módulo //!

Zig también tiene comentarios de documentación para el contenedor actual, usando //!.

Normalmente aparecen al principio de un archivo, para explicar qué representa ese módulo.

//! Utilidades matemáticas básicas para el curso de Zig.
//!
//! Este módulo contiene funciones pequeñas usadas en los ejemplos.

const std = @import("std");

La diferencia es sencilla:

• /// documenta la declaración que viene justo después.
• //! documenta el archivo o contenedor donde está escrito.

Comentarios y código limpio

Hay una tentación habitual cuando estamos aprendiendo: comentar absolutamente todo.

// Declaramos una variable llamada contador
var contador: u32 = 0;

// Sumamos uno al contador
contador += 1;

Esto no aporta demasiado. El código ya lo decía solo, y el comentario se convierte en ruido.

En cambio, este comentario sí ayuda:

// El contador empieza en 1 porque el protocolo reserva el 0 como valor inválido.
var contador: u32 = 1;

Ahí el comentario explica una regla externa al código. Eso sí merece quedarse.

Comentarios en APIs públicas

En Zig se valora mucho que el código sea explícito. Si una función forma parte de una API pública, especialmente si es pub, lo normal es documentarla con ///.

/// Busca un usuario por identificador.
///
/// Devuelve `null` si no existe ningún usuario con ese `id`.
pub fn buscarUsuario(id: u32) ?Usuario {
    // ...
}