Commentaires Verilog : ligne unique, multiligne et style documentation

Les deux formes

Verilog supporte exactement deux syntaxes de commentaires, toutes deux copiées de C :

// Commentaire sur une ligne - tout après // jusqu'à la fin de la ligne est ignoré.

/* Commentaire multiligne.
   Peut s'étendre sur autant de lignes que tu veux.
   Se ferme avec le star-slash correspondant. */

module example;
    initial begin
        $display("le simulateur ne voit jamais les commentaires ci-dessus");
        $finish;
    end
endmodule

Voilà toute la syntaxe. Pas de # comme en Python, pas de -- comme en VHDL, pas de style Lisp. Juste // et /* ... */.

Quand utiliser quoi

// est ce vers quoi tu te tournes presque tout le temps. C'est plus court, ne peut pas être accidentellement non terminé, et s'accorde naturellement avec la façon dont tu écris du Verilog (une déclaration par ligne, avec le commentaire sur la même ligne ou la ligne adjacente) :

output reg [7:0] data,  // octet qu'on décale sur tx_serial
output reg       valid, // haut pendant la transmission
input  wire      ready  // le consommateur en aval est prêt à accepter

/* ... */ sert surtout à deux choses : les gros blocs d'en-tête en haut d'un fichier, et la désactivation temporaire d'un morceau de code pendant le debug. Le cas désactivation est dangereux - lis la suite.

Le piège du « pas d'imbrication »

Les commentaires bloc ne s'imbriquent pas. Si tu essaies de commenter une zone qui contient déjà un commentaire bloc, le premier */ ferme le bloc externe, pas l'interne :

/* externe
   /* interne */    // <-- ce */ ferme le commentaire externe
   toujours actif dans le source pour le parser
*/

Résultat : une erreur de syntaxe quelque part inattendu, sur une ligne qui paraît correcte.

Quand tu as besoin de désactiver une zone, préfère l'une de ces options :

1. Préfixer chaque ligne avec //. La plupart des éditeurs font ça avec un raccourci clavier.

2. Utiliser un garde du préprocesseur :

   `ifdef DISABLED
       // code qui ne doit pas compiler
   `endif
   

Le second motif est aussi la façon de garder plusieurs configurations de build dans un seul fichier.

Pragmas de synthèse : des commentaires qui n'en sont pas

Les outils constructeurs utilisent des commentaires au format spécial comme instructions hors-bande. Le simulateur les ignore toujours, mais l'outil de synthèse les lit :

// synthesis translate_off
initial begin
    $display("setup pour la simulation uniquement");
end
// synthesis translate_on

Les deux pragmas disent à l'outil de synthèse « saute tout ce qui se trouve entre ces marqueurs ». L'orthographe exacte varie selon le constructeur (synthesis, synopsys, pragma, xilinx, etc.) - vérifie la doc de ton outil. Ce qu'il faut retenir : en Verilog, les commentaires sont parfois porteurs de sens.

Conventions de bloc d'en-tête

Les fichiers Verilog destinés à durer commencent presque toujours par un bloc d'en-tête. Le format exact est une politique d'équipe, mais un exemple typique :

// -----------------------------------------------------------------------------
// Module      : uart_tx
// Description : Émetteur UART 8-N-1. Accepte un octet sur `data` quand `valid`
//               est asserté et le décale sur `serial_out`. `baud_tick` doit
//               pulser une fois par période baud.
// Ports       : clk        - horloge système
//               reset_n    - reset synchrone actif-bas
//               baud_tick  - pulse d'1 cycle à chaque intervalle baud
//               data       - octet à transmettre
//               valid      - asserté pour démarrer une transmission
//               serial_out - le wire qui sort du FPGA
//               busy       - haut pendant qu'une trame est en cours
// Auteur      : example@team
// Révision    : 2026-05-26 - version initiale
// -----------------------------------------------------------------------------

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
);
    // ... corps ...
endmodule

L'important n'est pas la décoration. L'important, c'est que quelqu'un qui ouvre ce fichier dans un an - probablement toi - puisse lire quatre lignes et savoir ce qu'il fait, ce qu'il attend et ce qu'il produit. Ce gain monte en proportion de la taille du projet.

Commentaires inline qui gagnent leur place

Une erreur courante est de commenter le quoi d'une ligne quand le code le montre déjà :

// mauvais - le commentaire répète le code
count <= count + 1;   // incrémente count

// mieux - le commentaire explique pourquoi cette ligne est là
count <= count + 1;   // compteur de cycles libre pour l'horodatage

Ce pour quoi les commentaires sont uniquement utiles, c'est expliquer le pourquoi que le code ne peut pas montrer seul : quelle section du cahier des charges suit un encodage bizarre, pourquoi un registre est un bit plus large que ce qu'il paraît, pourquoi un default est mis à 'x plutôt qu'à '0. Mise sur eux pour ça. Laisse le reste au code.

Essaie-le

Le bloc ci-dessous contient toutes les formes de commentaires. Lance-le - la sortie ne te surprendra pas, mais la structure du fichier, si :

// -----------------------------------------------------------------------------
// Module      : full_adder
// Description : Additionneur complet 1 bit. Sorties `sum` et `cout` à partir de a, b, cin.
// -----------------------------------------------------------------------------

module full_adder(
    input  wire a,      // premier bit d'addition
    input  wire b,      // second bit d'addition
    input  wire cin,    // retenue entrante venant d'un additionneur d'ordre inférieur
    output wire sum,    // a XOR b XOR cin
    output wire cout    // (a AND b) OR (cin AND (a XOR b))
);
    /* Les deux équations ci-dessous sont un additionneur complet standard.
       Sum est la parité des trois entrées ; carry-out est
       la majorité des trois. */
    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
        // Balaye les 8 combinaisons d'entrée.
        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

Tu as maintenant vu toutes les formes de commentaires que Verilog supporte. Le reste de la documentation les utilise comme tu t'y attendrais : blocs d'en-tête en haut des longs modules, // simple ligne à côté des ports, et commentaires bloc seulement quand il y a un paragraphe entier de raisonnement à capturer.