Komentar Verilog: Satu Baris, Banyak Baris, dan Gaya Dokumentasi

Dua Bentuk Komentar

Verilog mendukung tepat dua sintaks komentar, keduanya disalin dari 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

Itulah seluruh sintaksnya. Tidak ada # seperti Python, tidak ada -- seperti VHDL, tidak ada gaya Lisp. Hanya // dan /* ... */.

Kapan Memakai Masing-Masing

// adalah yang hampir selalu kamu pakai. Lebih pendek, tidak mungkin lupa ditutup, dan cocok dengan cara menulis Verilog (satu deklarasi per baris, dengan komentar di baris yang sama atau di sebelahnya):

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

/* ... */ sebagian besar dipakai untuk dua hal: blok header besar di awal file, dan menonaktifkan sepotong kode sementara saat debug. Kasus menonaktifkan kode ini berbahaya, baca penjelasan berikut.

Jebakan "Tidak Bisa Bersarang"

Komentar blok tidak bisa bersarang. Kalau kamu mencoba mengomentari bagian yang sudah berisi komentar blok, */ pertama akan menutup blok luar, bukan blok dalam:

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

Hasilnya: syntax error di tempat yang tidak terduga, pada baris yang terlihat benar.

Saat kamu perlu menonaktifkan sebuah bagian, pilih salah satu cara ini:

1. Awali setiap baris dengan //. Kebanyakan editor bisa melakukannya dengan satu tombol pintas.

2. Pakai pelindung preprocessor:

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

Pola kedua juga cara untuk menyimpan beberapa konfigurasi build dalam satu file.

Pragma Sintesis: Komentar yang Bukan Sekadar Komentar

Tool vendor memakai komentar dengan format khusus sebagai instruksi tambahan. Simulator tetap mengabaikannya, tapi tool sintesis membacanya:

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

Kedua pragma itu memberi tahu tool sintesis "lewati semua yang ada di antara penanda ini". Ejaan pastinya berbeda-beda menurut vendor (synthesis, synopsys, pragma, xilinx, dan lain-lain), jadi cek dokumentasi tool-mu. Yang perlu kamu tahu: komentar di Verilog kadang punya fungsi penting.

Konvensi Blok Header

File Verilog yang dipakai lama hampir selalu diawali blok header. Format pastinya tergantung kebijakan tim, tapi contoh yang umum:

// -----------------------------------------------------------------------------
// 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

Intinya bukan hiasannya. Intinya, orang yang membuka file ini setahun lagi (kemungkinan besar kamu sendiri) bisa membaca empat baris dan langsung tahu fungsinya, apa yang ia butuhkan, dan apa yang ia hasilkan. Manfaatnya makin besar seiring bertambahnya ukuran proyek.

Komentar Inline yang Benar-Benar Berguna

Kesalahan yang umum adalah mengomentari apa yang dilakukan sebuah baris padahal kodenya sudah menunjukkan hal itu:

// 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

Hal yang paling bisa dilakukan komentar adalah menjelaskan alasan yang tidak bisa ditunjukkan kode itu sendiri: bagian spesifikasi mana yang diikuti oleh encoding yang aneh, kenapa sebuah register satu bit lebih lebar dari kelihatannya, kenapa case default diisi 'x alih-alih '0. Andalkan komentar untuk itu. Serahkan hal yang sudah jelas kepada kodenya.

Coba Sendiri

Blok di bawah berisi semua bentuk komentar. Jalankan: output-nya tidak akan mengejutkan, tapi struktur file-nya patut diperhatikan:

// -----------------------------------------------------------------------------
// 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

Sekarang kamu sudah melihat semua bentuk komentar yang didukung Verilog. Sisa dokumentasi ini memakainya seperti yang kamu duga: blok header di awal module yang panjang, // satu baris di sebelah port, dan komentar blok hanya saat ada penalaran sepanjang satu paragraf yang perlu dicatat.