Verilog Yorumlar: Tek Satır, Çok Satır ve Dokümantasyon Stili

İki Form

Verilog tam olarak iki yorum sözdizimini destekler, her ikisi de C'den kopyalanmıştır:

// Tek satır yorum - // sonrası satır sonuna kadar her şey yok sayılır.

/* Çok satırlı yorum.
   İstediğin kadar satır kapsayabilir.
   Eşleşen yıldız-eğik çizgi ile kapanır. */

module example;
    initial begin
        $display("simülatör yukarıdaki yorumları asla görmez");
        $finish;
    end
endmodule

Tüm sözdizimi budur. Python gibi # yok, VHDL gibi -- yok, Lisp tarzı yok. Sadece // ve /* ... */.

Hangisini Ne Zaman Kullanmalı

//, neredeyse her seferinde uzanacağındır. Daha kısadır, yanlışlıkla bitirilemez ve Verilog yazma şeklinle (satır başına bir tanımlama, yorum aynı veya komşu satırda) doğal olarak eşleşir:

output reg [7:0] data,  // tx_serial'de shift ettiğimiz byte
output reg       valid, // data iletilirken yüksek
input  wire      ready  // downstream consumer kabul etmeye hazır

/* ... */ çoğunlukla iki şey içindir: dosyanın üstündeki büyük header blokları ve debug yaparken bir kod parçasını geçici olarak devre dışı bırakmak. Devre dışı bırakma durumu tehlikelidir - devam et.

"Iç İçe Yok" Tuzağı

Blok yorumları iç içe geçmez. Zaten bir blok yorum içeren bir bölgeyi yorum yapmaya çalışırsan, ilk */ dıştaki bloğu değil, içerideki bloğu kapatır:

/* dış
   /* iç */    // <-- bu */ dış yorumu kapatır
   parser açısından kaynakta hala aktif
*/

Sonuç: doğru görünen bir satırda, beklenmedik bir yerde bir sözdizimi hatası.

Bir bölgeyi devre dışı bırakman gerektiğinde, şunlardan birini tercih et:

1. Her satırı // ile öneklen. Çoğu editör bunu bir tuş vuruşuyla yapar.

2. Bir preprocessor guard kullan:

   `ifdef DISABLED
       // derlenmemesi gereken kod
   `endif
   

İkinci kalıp aynı zamanda bir dosyada birden çok build konfigürasyonunu nasıl koruyacağındır.

Sentez Pragmaları: Yorum Olmayan Yorumlar

Vendor araçları, özel olarak biçimlendirilmiş yorumları bant dışı talimatlar olarak kullanır. Simülatör onları yine de yok sayar, ama sentez aracı onları okur:

// synthesis translate_off
initial begin
    $display("yalnızca simülatör kurulumu");
end
// synthesis translate_on

İki pragma sentez aracına "bu işaretler arasındaki her şeyi atla" der. Tam yazımlar vendor'a göre değişir (synthesis, synopsys, pragma, xilinx vb.) - aracının doc'larını kontrol et. Bilmen gereken şey: Verilog'daki yorumlar bazen yük taşır.

Header-Blok Gelenekleri

Uzun ömürlü Verilog dosyaları neredeyse her zaman bir header bloğuyla başlar. Tam format takım politikasıdır, ama tipik bir örnek:

// -----------------------------------------------------------------------------
// Module      : uart_tx
// Description : 8-N-1 UART transmitter. `valid` onaylandığında `data` üzerinde
//               bir byte kabul eder ve `serial_out` üzerinden shift eder.
//               `baud_tick` baud periyodu başına bir kez pulse vermeli.
// Ports       : clk        - sistem saati
//               reset_n    - active-low senkron reset
//               baud_tick  - her baud aralığında 1 döngülük pulse
//               data       - iletilecek byte
//               valid      - bir iletim başlatmak için onaylanır
//               serial_out - FPGA'dan çıkan wire
//               busy       - bir frame uçuştayken yüksek
// Author      : example@team
// Revision    : 2026-05-26 - ilk sürüm
// -----------------------------------------------------------------------------

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
);
    // ... gövde ...
endmodule

Önemli olan dekorasyon değil. Önemli olan, bu dosyayı bir yıl sonra - muhtemelen sen - açan birinin dört satır okuyup ne yaptığını, neyi beklediğini ve neyi ürettiğini bilebilmesidir. Bu getiri projenin büyüklüğüyle ölçeklenir.

Hak Ettiklerini Kazanan Inline Yorumlar

Yaygın bir hata, kod zaten gösterdiğinde bir satırın ne yaptığını yorumlamaktır:

// kötü - yorum kodu yeniden ifade ediyor
count <= count + 1;   // count'u artır

// daha iyi - yorum bu satırın neden burada olduğunu açıklıyor
count <= count + 1;   // zaman damgalama için serbest çalışan döngü sayacı

Yorumların eşsiz iyi olduğu şey, kodun kendi kendine gösteremeyeceği neden'i açıklamaktır: garip bir encoding'in hangi spec bölümünü takip ettiği, bir register'ın neden göründüğünden bir bit daha geniş olduğu, bir default case'in neden '0 yerine 'x'e ayarlandığı. Buna güven. Bariz olanı koda bırak.

Dene

Aşağıdaki blok her yorum formunu içerir. Çalıştır - çıkış seni şaşırtmayacak, ama dosya yapısı şaşırtmalı:

// -----------------------------------------------------------------------------
// Module      : full_adder
// Description : Bir bitlik full adder. a, b, cin'den `sum` ve `cout` çıkarır.
// -----------------------------------------------------------------------------

module full_adder(
    input  wire a,      // ilk addend bit
    input  wire b,      // ikinci addend bit
    input  wire cin,    // alt sıralı bir adder'dan carry in
    output wire sum,    // a XOR b XOR cin
    output wire cout    // (a AND b) OR (cin AND (a XOR b))
);
    /* Aşağıdaki iki denklem bir ders kitabı full-adder'ıdır.
       Sum üç girişin parity'sidir; carry-out
       üç-çoğunluktur. */
    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
        // 8 giriş kombinasyonunun hepsini süpür.
        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

Artık Verilog'un desteklediği her yorum şeklini gördün. Doc'ların geri kalanı bunları beklediğin gibi kullanır: uzun modüllerin üstünde header blokları, portların yanında tek satır // ve yalnızca yakalanacak bir paragrafın değerinde gerekçe olduğunda blok yorumlar.