Comentários em Verilog: linha única, múltiplas linhas e estilo de documentação

As duas formas

Verilog suporta exatamente duas sintaxes de comentário, ambas copiadas do C:

// Comentário de linha única - tudo depois de // até o fim da linha é ignorado.

/* Comentário multi-linha.
   Pode se estender por quantas linhas você quiser.
   Fecha com o asterisco-barra correspondente. */

module example;
    initial begin
        $display("o simulador nunca vê os comentários acima");
        $finish;
    end
endmodule

Essa é toda a sintaxe. Não há # como Python, nem -- como VHDL, nem estilo Lisp. Apenas // e /* ... */.

Quando usar cada um

// é o que você usa quase toda vez. É mais curto, não pode ser acidentalmente deixado sem terminar e combina naturalmente com a forma como você escreve Verilog (uma declaração por linha, com o comentário na mesma linha ou adjacente):

output reg [7:0] data,  // byte que deslocamos pelo tx_serial
output reg       valid, // alto enquanto data está sendo transmitido
input  wire      ready  // consumidor downstream está pronto para aceitar

/* ... */ é principalmente para duas coisas: blocos de cabeçalho grandes no topo de um arquivo e temporariamente desabilitar um trecho de código enquanto depura. O caso de desabilitar é perigoso - continue lendo.

A pegadinha do "sem aninhamento"

Comentários de bloco não aninham. Se você tentar comentar uma região que já contém um comentário de bloco, o primeiro */ fecha o bloco externo, não o interno:

/* externo
   /* interno */    // <-- este */ fecha o comentário externo
   ainda ativo no fonte para o parser
*/

Resultado: um erro de sintaxe em algum lugar inesperado, numa linha que parece correta.

Quando precisar desabilitar uma região, prefira uma de:

1. Prefixe cada linha com //. A maioria dos editores faz isso com um atalho.

2. Use uma guarda de pré-processador:

   `ifdef DISABLED
       // código que não deve compilar
   `endif
   

O segundo padrão também é como você mantém múltiplas configurações de build em um arquivo.

Pragmas de síntese: comentários que não são comentários

Ferramentas de fornecedores usam comentários com formato especial como instruções fora-de-banda. O simulador ainda os ignora, mas a ferramenta de síntese os lê:

// synthesis translate_off
initial begin
    $display("setup só para o simulador");
end
// synthesis translate_on

Os dois pragmas dizem à ferramenta de síntese "pule tudo entre estes marcadores". As ortografias exatas variam por fornecedor (synthesis, synopsys, pragma, xilinx, etc.) - veja a documentação da sua ferramenta. O que importa saber: comentários em Verilog às vezes carregam carga.

Convenções de bloco de cabeçalho

Arquivos Verilog de longa duração quase sempre começam com um bloco de cabeçalho. O formato exato é política de equipe, mas um exemplo típico:

// -----------------------------------------------------------------------------
// Module      : uart_tx
// Description : Transmissor UART 8-N-1. Aceita um byte em `data` quando `valid`
//               é asserido e o desloca em `serial_out`. `baud_tick`
//               precisa pulsar uma vez por período de baud.
// Ports       : clk        - clock do sistema
//               reset_n    - reset síncrono ativo-baixo
//               baud_tick  - pulso de 1 ciclo a cada intervalo de baud
//               data       - byte a transmitir
//               valid      - asserido para iniciar uma transmissão
//               serial_out - o wire que sai do FPGA
//               busy       - alto enquanto um frame está em trânsito
// Author      : example@team
// Revision    : 2026-05-26 - versão inicial
// -----------------------------------------------------------------------------

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
);
    // ... corpo ...
endmodule

O ponto não é a decoração. O ponto é que alguém abrindo este arquivo daqui a um ano - provavelmente você - pode ler quatro linhas e saber o que ele faz, o que espera e o que produz. Esse retorno escala com o tamanho do projeto.

Comentários inline que ganham o pão

Um erro comum é comentar o que uma linha faz quando o código já mostra:

// ruim - o comentário repete o código
count <= count + 1;   // incrementa count

// melhor - o comentário explica por que esta linha está aqui
count <= count + 1;   // contador de ciclos free-running para timestamping

A coisa em que comentários são unicamente bons é em explicar o porquê que o código não consegue mostrar por si só: qual seção da spec uma codificação esquisita segue, por que um register é um bit mais largo do que parece, por que um caso default é definido como 'x em vez de '0. Apoie-se neles para isso. Deixe o óbvio para o código.

Experimente

O bloco abaixo contém todas as formas de comentário. Execute-o - a saída não vai surpreender, mas a estrutura do arquivo deve:

// -----------------------------------------------------------------------------
// Module      : full_adder
// Description : Somador completo de um bit. Saídas `sum` e `cout` a partir de a, b, cin.
// -----------------------------------------------------------------------------

module full_adder(
    input  wire a,      // primeiro bit somando
    input  wire b,      // segundo bit somando
    input  wire cin,    // carry in vindo de um somador de ordem mais baixa
    output wire sum,    // a XOR b XOR cin
    output wire cout    // (a AND b) OR (cin AND (a XOR b))
);
    /* As duas equações abaixo são um full-adder de manual.
       Sum é a paridade das três entradas; carry-out é
       maioria-de-três. */
    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
        // Varre as 8 combinações 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

Você agora viu todas as formas de comentário que o Verilog suporta. O resto dos docs os usa como você esperaria: blocos de cabeçalho no topo de modules longos, // de linha única ao lado de ports e comentários de bloco só quando há um parágrafo de raciocínio para capturar.