Komentarze w Verilogu: jednoliniowe, wieloliniowe i dokumentacja

Dwie formy

Verilog obsługuje dokładnie dwie składnie komentarzy, obie skopiowane z C:

// Komentarz jednoliniowy: wszystko od // do końca linii jest ignorowane.

/* Komentarz wieloliniowy.
   Może zajmować dowolnie wiele linii.
   Zamyka go pasująca para gwiazdka-ukośnik. */

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

To cała składnia. Nie ma # jak w Pythonie, -- jak w VHDL ani stylu z Lispa. Tylko // i /* ... */.

Kiedy używać której

Po // sięgasz prawie zawsze. Jest krótszy, nie da się go przypadkiem zostawić niezamkniętego i naturalnie pasuje do sposobu pisania w Verilogu (jedna deklaracja na linię, z komentarzem w tej samej lub sąsiedniej linii):

output reg [7:0] data,  // bajt, który wysyłamy przez tx_serial
output reg       valid, // wysoki, dopóki data jest nadawany
input  wire      ready  // odbiorca dalej w torze jest gotowy przyjąć dane

/* ... */ służy głównie do dwóch rzeczy: dużych bloków nagłówkowych na początku pliku i tymczasowego wyłączania fragmentu kodu podczas debugowania. Wyłączanie jest ryzykowne, o czym dalej.

Pułapka: brak zagnieżdżania

Komentarze blokowe się nie zagnieżdżają. Jeśli spróbujesz zakomentować fragment, który zawiera już komentarz blokowy, pierwsze */ zamknie blok zewnętrzny, a nie wewnętrzny:

/* zewnętrzny
   /* wewnętrzny */    // <-- to */ zamyka zewnętrzny komentarz
   dla parsera to wciąż aktywny kod źródłowy
*/

Efekt: błąd składni w nieoczekiwanym miejscu, w linii, która wygląda poprawnie.

Gdy musisz wyłączyć fragment kodu, wybierz raczej jedno z poniższych:

1. Poprzedź każdą linię przez //. Większość edytorów robi to jednym skrótem klawiszowym.

2. Użyj osłony preprocesora:

   `ifdef DISABLED
       // kod, który nie powinien się kompilować
   `endif
   

Drugi wzorzec pozwala też trzymać kilka konfiguracji builda w jednym pliku.

Pragmy syntezy: komentarze, które nie są komentarzami

Narzędzia producentów używają specjalnie sformatowanych komentarzy jako dodatkowych instrukcji. Symulator nadal je ignoruje, ale narzędzie do syntezy je czyta:

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

Te dwie pragmy mówią narzędziu do syntezy "pomiń wszystko między tymi znacznikami". Dokładna pisownia zależy od producenta (synthesis, synopsys, pragma, xilinx itd.), więc sprawdź dokumentację swojego narzędzia. Warto wiedzieć jedno: komentarze w Verilogu czasem naprawdę coś robią.

Konwencje bloków nagłówkowych

Pliki Verilog, które mają długo żyć, prawie zawsze zaczynają się od bloku nagłówkowego. Dokładny format to kwestia zasad zespołu, ale typowy przykład wygląda tak:

// -----------------------------------------------------------------------------
// Module      : uart_tx
// Description : Nadajnik UART 8-N-1. Przyjmuje bajt z `data`, gdy `valid`
//               jest aktywny, i wysuwa go przez `serial_out`. `baud_tick`
//               musi dać jeden impuls na każdy okres bodu.
// Ports       : clk        - zegar systemowy
//               reset_n    - synchroniczny reset aktywny niskim stanem
//               baud_tick  - impuls trwający 1 cykl w każdym interwale bodu
//               data       - bajt do wysłania
//               valid      - aktywowany, żeby rozpocząć transmisję
//               serial_out - wire, który wychodzi z FPGA
//               busy       - wysoki, dopóki ramka jest w drodze
// 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

Nie chodzi o ozdobniki. Chodzi o to, żeby ktoś, kto otworzy ten plik za rok (prawdopodobnie ty), mógł przeczytać cztery linie i wiedzieć, co moduł robi, czego oczekuje i co zwraca. Ta korzyść rośnie razem z rozmiarem projektu.

Komentarze w linii, które są coś warte

Częsty błąd to komentowanie, co robi linia, gdy kod już to pokazuje:

// źle: komentarz powtarza kod
count <= count + 1;   // zwiększ count

// lepiej: komentarz wyjaśnia, po co jest ta linia
count <= count + 1;   // licznik cykli działający bez przerwy, do znaczników czasu

Komentarze wyjątkowo dobrze wyjaśniają dlaczego, czego kod sam nie pokaże: którą sekcję specyfikacji realizuje dziwne kodowanie, czemu rejestr jest o bit szerszy, niż się wydaje, czemu przypadek default ustawiono na 'x zamiast na '0. Używaj ich właśnie do tego. Oczywiste rzeczy zostaw kodowi.

Wypróbuj

Poniższy blok zawiera wszystkie formy komentarzy. Uruchom go: wynik cię nie zaskoczy, ale struktura pliku powinna dać do myślenia:

// -----------------------------------------------------------------------------
// Module      : full_adder
// Description : Jednobitowy sumator pełny. Wyznacza `sum` i `cout` z a, b, cin.
// -----------------------------------------------------------------------------

module full_adder(
    input  wire a,      // pierwszy bit składnika
    input  wire b,      // drugi bit składnika
    input  wire cin,    // przeniesienie z sumatora niższego rzędu
    output wire sum,    // a XOR b XOR cin
    output wire cout    // (a AND b) OR (cin AND (a XOR b))
);
    /* Dwa poniższe równania to podręcznikowy sumator pełny.
       Sum to parzystość trzech wejść, a cout to
       większość z trzech. */
    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
        // Przejdź przez wszystkie 8 kombinacji wejść.
        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

Znasz już wszystkie kształty komentarzy, które obsługuje Verilog. Pozostałe strony dokumentacji używają ich tak, jak można się spodziewać: bloki nagłówkowe na początku długich modułów, jednoliniowe // przy portach, a komentarze blokowe tylko wtedy, gdy trzeba zapisać cały akapit rozumowania.