Comentarios en Verilog: una línea, múltiples líneas y estilo de documentación

Las dos formas

Verilog soporta exactamente dos sintaxis de comentario, ambas copiadas de C:

// Comentario de una línea - todo lo que va después de // hasta el final de la línea se ignora.

/* Comentario de varias líneas.
   Puede abarcar tantas líneas como quieras.
   Se cierra con el slash-estrella correspondiente. */

module example;
    initial begin
        $display("the simulator never sees the comments above");
        $finish;
    end
endmodule

Esa es toda la sintaxis. No hay # como en Python, ni -- como en VHDL, ni estilo Lisp. Solo // y /* ... */.

Cuándo usar cada uno

// es lo que vas a usar casi siempre. Es más corto, no puede quedar accidentalmente sin terminar y va de forma natural con la manera de escribir Verilog (una declaración por línea, con el comentario en la misma línea o adyacente):

output reg [7:0] data,  // byte que sacamos por tx_serial
output reg       valid, // alto mientras se transmite el data
input  wire      ready  // el consumidor downstream está listo para aceptar

/* ... */ es sobre todo para dos cosas: grandes bloques de encabezado en la parte superior de un archivo, y deshabilitar temporalmente un trozo de código durante depuración. El caso de deshabilitar es peligroso - sigue leyendo.

La trampa de "no se anida"

Los comentarios de bloque no se anidan. Si intentas comentar una región que ya contiene un comentario de bloque, el primer */ cierra el bloque externo, no el interno:

/* externo
   /* interno */    // <-- este */ cierra el comentario externo
   sigue activo en el código fuente para el parser
*/

Resultado: un error de sintaxis en algún punto inesperado, en una línea que parece correcta.

Cuando necesites deshabilitar una región, prefiere una de:

1. Prefijar cada línea con //. La mayoría de los editores hacen esto con una tecla.

2. Usar una protección de preprocesador:

   `ifdef DISABLED
       // código que no debería compilar
   `endif
   

El segundo patrón es también cómo mantienes varias configuraciones de build en un solo archivo.

Pragmas de síntesis: comentarios que no son comentarios

Las herramientas de los proveedores usan comentarios con formato especial como instrucciones fuera de banda. El simulador los sigue ignorando, pero la herramienta de síntesis los lee:

// synthesis translate_off
initial begin
    $display("simulator-only setup");
end
// synthesis translate_on

Los dos pragmas le dicen a la herramienta de síntesis "salta todo entre estos marcadores". Las formas exactas varían según el proveedor (synthesis, synopsys, pragma, xilinx, etc.) - consulta los docs de tu herramienta. Lo que hay que saber: los comentarios en Verilog a veces son funcionales.

Convenciones de bloque de encabezado

Los archivos Verilog de larga vida casi siempre empiezan con un bloque de encabezado. El formato exacto es política del equipo, pero un ejemplo típico:

// -----------------------------------------------------------------------------
// Module      : uart_tx
// Description : Transmisor UART 8-N-1. Acepta un byte en `data` cuando `valid`
//               está activado y lo desplaza por `serial_out`. `baud_tick`
//               debe pulsar una vez por periodo de baudio.
// Ports       : clk        - reloj del sistema
//               reset_n    - reset síncrono activo en bajo
//               baud_tick  - pulso de 1 ciclo en cada intervalo de baudio
//               data       - byte a transmitir
//               valid      - se activa para iniciar una transmisión
//               serial_out - el wire que sale de la FPGA
//               busy       - alto mientras un frame está en vuelo
// Author      : example@team
// Revision    : 2026-05-26 - initial version
// -----------------------------------------------------------------------------

module uart_tx (
    input  wire       clk,
    input  wire       reset_n,
    input  wire       baud_tick,
    input  wire [7:0] data,
    input  wire       valid,
    output reg        serial_out,
    output reg        busy
);
    // ... body ...
endmodule

El punto no es la decoración. El punto es que alguien que abra este archivo dentro de un año - probablemente tú - pueda leer cuatro líneas y saber qué hace, qué espera y qué produce. Ese beneficio escala con el tamaño del proyecto.

Comentarios en línea que se ganan su sitio

Un error común es comentar qué hace una línea cuando el código ya lo muestra:

// mal - el comentario repite el código
count <= count + 1;   // incrementa count

// mejor - el comentario explica por qué esta línea está aquí
count <= count + 1;   // contador de ciclos libre para timestamping

En lo que los comentarios son especialmente buenos es en explicar el por qué que el código no puede mostrar por sí solo: qué sección de la especificación sigue una codificación rara, por qué un registro es un bit más ancho de lo que parece, por qué un caso default está puesto a 'x en vez de a '0. Apóyate en ellos para eso. Deja lo obvio al código.

Pruébalo

El bloque de abajo contiene cada forma de comentario. Ejecútalo - la salida no te va a sorprender, pero la estructura del archivo sí debería:

// -----------------------------------------------------------------------------
// Module      : full_adder
// Description : Sumador completo de un bit. Saca `sum` y `cout` a partir de a, b, cin.
// -----------------------------------------------------------------------------

module full_adder(
    input  wire a,      // primer bit sumando
    input  wire b,      // segundo bit sumando
    input  wire cin,    // acarreo de entrada de un sumador de orden inferior
    output wire sum,    // a XOR b XOR cin
    output wire cout    // (a AND b) OR (cin AND (a XOR b))
);
    /* Las dos ecuaciones de abajo son un sumador completo de manual.
       Sum es la paridad de las tres entradas; cout es
       mayoría-de-tres. */
    assign sum  = a ^ b ^ cin;
    assign cout = (a & b) | (cin & (a ^ b));
endmodule

module test;
    reg  a, b, cin;
    wire sum, cout;

    full_adder dut(.a(a), .b(b), .cin(cin), .sum(sum), .cout(cout));

    initial begin
        // Barre las 8 combinaciones de entrada.
        for (integer i = 0; i < 8; i = i + 1) begin
            {a, b, cin} = i[2:0];
            #1 $display("a=%b b=%b cin=%b -> sum=%b cout=%b",
                        a, b, cin, sum, cout);
        end
        $finish;
    end
endmodule

Ya has visto cada forma de comentario que Verilog soporta. El resto de los docs los usan como cabe esperar: bloques de encabezado en la parte superior de módulos largos, // de una línea junto a los puertos, y comentarios de bloque solo cuando hay un párrafo entero de razonamiento que capturar.