Commenti in Verilog: su una riga, su più righe e stile di documentazione

Le due forme

Verilog supporta esattamente due sintassi di commento, entrambe copiate dal C:

// Commento su una riga: tutto ciò che segue // fino a fine riga viene ignorato.

/* Commento su più righe.
   Può occupare tutte le righe che vuoi.
   Si chiude con il corrispondente asterisco-slash. */

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

Questa è tutta la sintassi. Niente # come in Python, niente -- come in VHDL, niente stile Lisp. Solo // e /* ... */.

Quando usare l'uno o l'altro

// è quello che userai quasi sempre. È più corto, non può restare aperto per sbaglio e si sposa bene con il modo in cui si scrive Verilog (una dichiarazione per riga, con il commento sulla stessa riga o su quella accanto):

output reg [7:0] data,  // byte che trasmettiamo su tx_serial
output reg       valid, // alto mentre data viene trasmesso
input  wire      ready  // il consumatore a valle è pronto ad accettare

/* ... */ serve soprattutto per due cose: grandi blocchi di intestazione in cima a un file e disattivare temporaneamente un pezzo di codice durante il debug. Il secondo caso è pericoloso: continua a leggere.

La trappola del "niente annidamento"

I commenti a blocco non si annidano. Se provi a commentare una regione che contiene già un commento a blocco, il primo */ chiude il blocco esterno, non quello interno:

/* esterno
   /* interno */    // <-- questo */ chiude il commento esterno
   per il parser questa riga è ancora codice attivo
*/

Risultato: un errore di sintassi in un punto inatteso, su una riga che sembra corretta.

Quando devi disattivare una regione, scegli una di queste strade:

1. Metti // all'inizio di ogni riga. La maggior parte degli editor lo fa con una scorciatoia da tastiera.

2. Usa una guardia del preprocessore:

   `ifdef DISABLED
       // codice che non deve essere compilato
   `endif
   

Il secondo pattern è anche il modo in cui si gestiscono più configurazioni di build in un solo file.

Pragma di sintesi: commenti che non sono commenti

Gli strumenti dei produttori usano commenti con un formato speciale come istruzioni fuori banda. Il simulatore continua a ignorarli, ma lo strumento di sintesi li legge:

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

I due pragma dicono allo strumento di sintesi "salta tutto ciò che sta tra questi marcatori". La grafia esatta cambia da produttore a produttore (synthesis, synopsys, pragma, xilinx, ecc.): controlla la documentazione del tuo strumento. Quello che devi sapere: in Verilog i commenti a volte hanno un effetto reale.

Convenzioni per i blocchi di intestazione

I file Verilog destinati a durare iniziano quasi sempre con un blocco di intestazione. Il formato esatto lo decide il team, ma ecco un esempio tipico:

// -----------------------------------------------------------------------------
// Module      : uart_tx
// Description : Trasmettitore UART 8-N-1. Accetta un byte su `data` quando
//               `valid` è attivo e lo trasmette bit per bit su `serial_out`.
//               `baud_tick` deve pulsare una volta per periodo di baud.
// Ports       : clk        - clock di sistema
//               reset_n    - reset sincrono attivo basso
//               baud_tick  - impulso di 1 ciclo a ogni intervallo di baud
//               data       - byte da trasmettere
//               valid      - attivato per avviare una trasmissione
//               serial_out - il wire che esce dalla FPGA
//               busy       - alto mentre un frame è in trasmissione
// 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

Il punto non è la decorazione. Il punto è che chi apre questo file fra un anno (probabilmente tu) possa leggere quattro righe e sapere cosa fa, cosa si aspetta e cosa produce. Il vantaggio cresce con le dimensioni del progetto.

Commenti in linea che valgono la pena

Un errore comune è commentare cosa fa una riga quando il codice lo mostra già:

// male: il commento ripete il codice
count <= count + 1;   // incrementa count

// meglio: il commento spiega perché questa riga è qui
count <= count + 1;   // contatore di cicli libero per i timestamp

Ciò in cui i commenti sono davvero insostituibili è spiegare il perché che il codice da solo non può mostrare: quale sezione della specifica segue una codifica strana, perché un registro è un bit più largo di quanto sembri, perché un caso default è impostato a 'x invece che a '0. Usali per questo. Lascia l'ovvio al codice.

Provalo

Il blocco qui sotto contiene tutte le forme di commento. Eseguilo: l'output non ti sorprenderà, ma la struttura del file dovrebbe farlo:

// -----------------------------------------------------------------------------
// Module      : full_adder
// Description : Sommatore completo a un bit. Produce `sum` e `cout` da a, b, cin.
// -----------------------------------------------------------------------------

module full_adder(
    input  wire a,      // primo bit addendo
    input  wire b,      // secondo bit addendo
    input  wire cin,    // riporto in ingresso da un sommatore di ordine inferiore
    output wire sum,    // a XOR b XOR cin
    output wire cout    // (a AND b) OR (cin AND (a XOR b))
);
    /* Le due equazioni qui sotto sono un sommatore completo da manuale.
       Sum è la parità dei tre ingressi; cout è
       la maggioranza su tre. */
    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
        // Prova tutte le 8 combinazioni di ingresso.
        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

Ora hai visto tutte le forme di commento che Verilog supporta. Il resto delle guide le usa come ti aspetteresti: blocchi di intestazione in cima ai moduli lunghi, // su una riga accanto alle porte e commenti a blocco solo quando c'è un intero paragrafo di ragionamento da mettere per iscritto.