Verilog Comments: Single-Line, Multi-Line, and Documentation Style

The Two Forms

Verilog supports exactly two comment syntaxes, both copied from C:

// Single-line comment - everything after // to end of line is ignored.

/* Multi-line comment.
   Can span as many lines as you like.
   Closes with the matching star-slash. */

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

That's the whole syntax. There's no # like Python, no -- like VHDL, no Lisp-style. Just // and /* ... */.

When to Use Each

// is what you reach for almost every time. It's shorter, it can't be accidentally unterminated, and it pairs naturally with the way you write Verilog (one declaration per line, with the comment on the same or adjacent line):

output reg [7:0] data,  // byte we shift out on tx_serial
output reg       valid, // high while data is being transmitted
input  wire      ready  // downstream consumer is ready to accept

/* ... */ is mostly for two things: large header blocks at the top of a file, and temporarily disabling a chunk of code while debugging. The disable case is dangerous - read on.

The "No Nesting" Gotcha

Block comments don't nest. If you try to comment out a region that already contains a block comment, the first */ closes the outer block, not the inner:

/* outer
   /* inner */    // <-- this */ closes the outer comment
   still active in the source as far as the parser is concerned
*/

Result: a syntax error somewhere unexpected, on a line that looks correct.

When you need to disable a region, prefer one of:

1. Prefix every line with //. Most editors do this on a keystroke.

2. Use a preprocessor guard:

   `ifdef DISABLED
       // code that should not compile
   `endif
   

The second pattern is also how you keep multiple build configurations in one file.

Synthesis Pragmas: Comments That Aren't Comments

Vendor tools use specially-formatted comments as out-of-band instructions. The simulator still ignores them, but the synthesis tool reads them:

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

The two pragmas tell the synthesis tool "skip everything between these markers." The exact spellings vary by vendor (synthesis, synopsys, pragma, xilinx, etc.) - check your tool's docs. The thing to know: comments in Verilog are sometimes load-bearing.

Header-Block Conventions

Long-lived Verilog files almost always start with a header block. The exact format is team policy, but a typical example:

// -----------------------------------------------------------------------------
// Module      : uart_tx
// Description : 8-N-1 UART transmitter. Accepts a byte on `data` when `valid`
//               is asserted and shifts it out on `serial_out`. `baud_tick`
//               must pulse once per baud period.
// Ports       : clk        - system clock
//               reset_n    - active-low synchronous reset
//               baud_tick  - 1-cycle pulse at each baud interval
//               data       - byte to transmit
//               valid      - asserted to start a transmission
//               serial_out - the wire that leaves the FPGA
//               busy       - high while a frame is in flight
// 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

The point isn't the decoration. The point is that someone opening this file in a year - probably you - can read four lines and know what it does, what it expects, and what it produces. That payoff scales with the size of the project.

Inline Comments That Earn Their Keep

A common mistake is commenting what a line does when the code already shows that:

// bad - the comment restates the code
count <= count + 1;   // increment count

// better - the comment explains why this line is here
count <= count + 1;   // free-running cycle counter for timestamping

The thing comments are uniquely good at is explaining the why that the code can't show by itself: which spec section a quirky encoding follows, why a register is one bit wider than it looks, why a default case is set to 'x instead of '0. Lean on them for that. Leave the obvious to the code.

Try It

The block below contains every comment form. Run it - the output won't surprise you, but the file structure should:

// -----------------------------------------------------------------------------
// Module      : full_adder
// Description : One-bit full adder. Outputs `sum` and `cout` from a, b, cin.
// -----------------------------------------------------------------------------

module full_adder(
    input  wire a,      // first addend bit
    input  wire b,      // second addend bit
    input  wire cin,    // carry in from a lower-order adder
    output wire sum,    // a XOR b XOR cin
    output wire cout    // (a AND b) OR (cin AND (a XOR b))
);
    /* The two equations below are a textbook full-adder.
       Sum is the parity of the three inputs; carry-out is
       majority-of-three. */
    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
        // Sweep all 8 input combinations.
        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

You've now seen every comment shape Verilog supports. The rest of the docs use them as you'd expect: header blocks at the top of long modules, single-line // next to ports, and block comments only when there's a paragraph's worth of reasoning to capture.