تعليقات Verilog: سطر واحد، متعددة الأسطر، وأسلوب التوثيق

الشكلان

يدعم Verilog صياغتين فقط للتعليقات، كلاهما منسوخ من C:

// تعليق سطر واحد - كل شيء بعد // إلى نهاية السطر يُتجاهل.

/* تعليق متعدد الأسطر.
   يمكن أن يمتد عبر أي عدد من الأسطر.
   يُغلق بنجمة-شرطة مائلة مطابقة. */

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

هذه الصياغة بأكملها. لا # كما في Python، ولا -- كما في VHDL، ولا أسلوب Lisp. فقط // و/* ... */.

متى تستخدم أيهما

// هو ما تلجأ إليه في كل مرة تقريبًا. أقصر، ولا يمكن تركه غير مُغلق بالخطأ، ويتوافق طبيعيًا مع طريقة كتابة Verilog (إعلان واحد لكل سطر، مع تعليق على نفس السطر أو السطر المجاور):

output reg [7:0] data,  // البايت الذي نزيحه على tx_serial
output reg       valid, // مرتفع أثناء نقل البيانات
input  wire      ready  // المستهلك في الأسفل جاهز للقبول

/* ... */ في الغالب لأمرين: كتل رأس كبيرة على قمة الملف، وتعطيل قطعة من الشيفرة مؤقتًا أثناء التنقيح. حالة التعطيل خطرة - تابع القراءة.

مأزق "عدم التداخل"

تعليقات الكتلة لا تتداخل. إن حاولت تعطيل منطقة تحوي بالفعل تعليق كتلة، فإن أول */ يُغلق الكتلة الخارجية، لا الداخلية:

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

النتيجة: خطأ صياغي في مكان غير متوقع، على سطر يبدو صحيحًا.

عندما تحتاج إلى تعطيل منطقة، فضّل أحد البدائل:

1. اسبق كل سطر بـ //. معظم المحررات تفعل ذلك بضربة مفتاح.

2. استخدم حارس preprocessor:

   `ifdef DISABLED
       // شيفرة لا ينبغي ترجمتها
   `endif
   

النمط الثاني هو أيضًا كيف تُبقي على إعدادات بناء متعددة في ملف واحد.

Synthesis Pragmas: تعليقات ليست تعليقات

تستخدم أدوات الشركات تعليقات بصياغة خاصة بوصفها تعليمات خارج الباند (out-of-band). المحاكي ما زال يتجاهلها، لكن أداة التركيب تقرؤها:

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

تخبر هاتان الـ pragmas أداة التركيب "تخطّى كل شيء بين هاتين العلامتين". تختلف الكتابة الدقيقة بحسب الشركة (synthesis، synopsys، pragma، xilinx، إلخ) - راجع وثائق أداتك. ما يجب معرفته: التعليقات في Verilog أحيانًا تحمل وظيفة.

أعراف كتل الرأس (Header)

ملفات Verilog طويلة العمر تبدأ غالبًا بكتلة رأس. التنسيق الدقيق يُحدّده الفريق، لكن المثال المعتاد:

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

ليس الزخرف هو الغاية. الغاية أن يستطيع من يفتح هذا الملف بعد سنة - الأرجح أن يكون أنت - أن يقرأ أربعة أسطر فيعرف ما يفعله، وما يتوقعه، وما يُنتجه. هذا العائد يتضاعف مع حجم المشروع.

التعليقات المضمّنة التي تستحق وجودها

من الأخطاء الشائعة التعليق على ماذا يفعل السطر بينما تُظهر الشيفرة ذلك أصلًا:

// سيئ - التعليق يُعيد ذكر ما تفعله الشيفرة
count <= count + 1;   // increment count

// أفضل - التعليق يشرح لماذا يوجد هذا السطر
count <= count + 1;   // free-running cycle counter for timestamping

الشيء الذي تتفوّق فيه التعليقات بوضوح هو شرح لماذا لا يمكن للشيفرة أن تُظهره وحدها: أي قسم من المواصفات يُتّبع في تشفير غريب، ولماذا register أعرض ببت واحدة مما يبدو، ولماذا حالة default مُسندَة إلى 'x بدلًا من '0. اعتمد عليها في ذلك. واترك الواضح للشيفرة.

جرّب

الكتلة أدناه تحوي كل أشكال التعليقات. شغّلها - الخرج لن يفاجئك، لكن بنية الملف يجب أن تفعل:

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

شاهدت الآن كل شكل تعليق يدعمه Verilog. باقي المستندات تستخدمها كما تتوقع: كتل رأس على قمة modules الطويلة، و// بسطر واحد بجوار المنافذ، وتعليقات الكتلة فقط عندما يوجد فقرة كاملة من التفكير يجب التقاطها.