Verilog Kommentare: Einzeilig, mehrzeilig und Dokumentations-Stil

Die zwei Formen

Verilog unterstützt genau zwei Kommentar-Syntaxen, beide aus C übernommen:

// Einzeiliger Kommentar - alles nach // bis Zeilenende wird ignoriert.

/* Mehrzeiliger Kommentar.
   Kann beliebig viele Zeilen umfassen.
   Endet mit dem passenden Stern-Slash. */

module example;
    initial begin
        $display("der Simulator sieht die Kommentare oben nie");
        $finish;
    end
endmodule

Das ist die ganze Syntax. Es gibt kein # wie in Python, kein -- wie in VHDL, keinen Lisp-Stil. Nur // und /* ... */.

Wann was nehmen

// ist das, wozu du fast immer greifst. Kürzer, kann nicht versehentlich unbeendet bleiben und passt natürlich zur Art, wie du Verilog schreibst (eine Deklaration pro Zeile, Kommentar in derselben oder benachbarten Zeile):

output reg [7:0] data,  // Byte, das wir auf tx_serial hinausschieben
output reg       valid, // high, während Daten übertragen werden
input  wire      ready  // nachgelagerter Konsument ist bereit

/* ... */ ist hauptsächlich für zwei Dinge gedacht: große Header-Blöcke oben in einer Datei und temporäres Deaktivieren eines Codestücks beim Debuggen. Der Deaktivierungs-Fall ist gefährlich - lies weiter.

Die "Keine Verschachtelung"-Falle

Block-Kommentare verschachteln sich nicht. Wenn du einen Bereich auskommentieren willst, der bereits einen Block-Kommentar enthält, schließt das erste */ den äußeren Block, nicht den inneren:

/* äußerer
   /* innerer */    // <-- dieses */ schließt den äußeren Kommentar
   weiterhin aktiv im Quelltext, was den Parser angeht
*/

Ergebnis: ein Syntaxfehler an einer unerwarteten Stelle, in einer Zeile, die korrekt aussieht.

Wenn du einen Bereich deaktivieren willst, bevorzuge:

1. Jede Zeile mit // präfixen. Die meisten Editoren tun das per Tastendruck.

2. Eine Präprozessor-Schutzdirektive nutzen:

   `ifdef DISABLED
       // Code, der nicht kompilieren soll
   `endif
   

Das zweite Muster ist auch der Weg, mehrere Build-Konfigurationen in einer Datei zu halten.

Synthese-Pragmas: Kommentare, die keine sind

Hersteller-Tools nutzen speziell formatierte Kommentare als Out-of-Band-Anweisungen. Der Simulator ignoriert sie weiterhin, aber das Synthese-Tool liest sie:

// synthesis translate_off
initial begin
    $display("simulationsspezifisches Setup");
end
// synthesis translate_on

Die zwei Pragmas sagen dem Synthese-Tool "überspringe alles zwischen diesen Markern". Die genauen Schreibweisen variieren je Hersteller (synthesis, synopsys, pragma, xilinx usw.) - prüfe die Tool-Docs. Wichtig zu wissen: Kommentare in Verilog sind manchmal tragend.

Header-Block-Konventionen

Langlebige Verilog-Dateien starten fast immer mit einem Header-Block. Das genaue Format ist Team-Policy, ein typisches Beispiel:

// -----------------------------------------------------------------------------
// Module      : uart_tx
// Description : 8-N-1 UART-Sender. Nimmt ein Byte auf `data`, wenn `valid`
//               aktiviert ist, und schiebt es auf `serial_out` hinaus.
//               `baud_tick` muss einmal pro Baud-Periode pulsen.
// Ports       : clk        - Systemtakt
//               reset_n    - active-low synchroner Reset
//               baud_tick  - 1-Zyklus-Puls in jedem Baud-Intervall
//               data       - zu sendendes Byte
//               valid      - aktiviert, um eine Übertragung zu starten
//               serial_out - die Leitung, die das FPGA verlässt
//               busy       - high, während ein Frame in Übertragung ist
// 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

Es geht nicht um die Dekoration. Es geht darum, dass jemand, der diese Datei in einem Jahr öffnet - wahrscheinlich du selbst -, in vier Zeilen weiß, was sie tut, was sie erwartet und was sie produziert. Der Lohn skaliert mit der Größe des Projekts.

Inline-Kommentare, die ihr Geld wert sind

Ein häufiger Fehler ist, das Was einer Zeile zu kommentieren, wenn der Code es bereits zeigt:

// schlecht - der Kommentar wiederholt den Code
count <= count + 1;   // count erhöhen

// besser - der Kommentar erklärt, warum die Zeile hier steht
count <= count + 1;   // freilaufender Zyklenzähler für Timestamping

Was Kommentare einzigartig gut können, ist das Warum zu erklären, das der Code nicht selbst zeigen kann: welcher Spec-Abschnitt einer komischen Kodierung folgt, warum ein Register ein Bit breiter ist als es aussieht, warum ein default-Case auf 'x statt '0 gesetzt ist. Setze dafür auf sie. Das Offensichtliche überlässt du dem Code.

Probier es aus

Der Block unten enthält jede Kommentar-Form. Lass ihn laufen - die Ausgabe wird dich nicht überraschen, aber die Dateistruktur sollte sich einprägen:

// -----------------------------------------------------------------------------
// Module      : full_adder
// Description : Ein-Bit-Volladdierer. Liefert `sum` und `cout` aus a, b, cin.
// -----------------------------------------------------------------------------

module full_adder(
    input  wire a,      // erstes Summandenbit
    input  wire b,      // zweites Summandenbit
    input  wire cin,    // Carry-In von einem niederwertigeren Addierer
    output wire sum,    // a XOR b XOR cin
    output wire cout    // (a AND b) OR (cin AND (a XOR b))
);
    /* Die beiden Gleichungen unten sind ein Lehrbuch-Volladdierer.
       Sum ist die Parität der drei Eingänge; Carry-Out ist
       Majorität-von-drei. */
    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
        // Alle 8 Eingangskombinationen durchspielen.
        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

Du hast jetzt jede Kommentar-Form gesehen, die Verilog unterstützt. Der Rest der Docs nutzt sie wie erwartet: Header-Blöcke oben in langen Modulen, einzeilige // neben Ports und Block-Kommentare nur, wenn es einen ganzen Absatz an Begründung einzufangen gibt.