実行できるVerilogドキュメント: コメント

Q: Verilogでコメントはどう書くのですか？

Verilogはどちらもからの2つのコメントスタイルをサポートします。//は行末までのコメントを開始します。/ ... /は複数行のブロックを囲みます。マーカー間はすべてコンパイラが無視します。両スタイルとも合成可能・シミュレーション専用どちらのファイルでも等しく有効です。

Q: Verilogコメントは合成されますか？

コメントはパース後には存在しません。合成ツールはシミュレータと同様に捨ててしまいます。唯一の例外は 合成プラグマ で、// synthesis translate_offのように特別な形式のコメントをベンダーツールがディレクティブとして認識します。プラグマ構文はツール固有で、標準Verilogの一部ではありません。

Q: Verilogコメントはネスト可能ですか？

いいえ。これは/ ... /を含むブロックをコメントアウトしようとする初心者を引っかけます。最初の*/が外側のコメントを閉じてしまい、残りのブロックは生きたコードのままになります。各行に//を使うか、本当に大きな塊を無効化したい場合は\ifdef SOMETHING_FALSE / \endifで囲んでください。

2つの形式

VerilogはちょうどCからコピーした2つのコメント構文をサポートします：

// 1行コメント - //から行末までは無視される。

/* 複数行コメント。
   好きなだけ行をまたげる。
   対応する星-スラッシュで閉じる。 */

module example;
    initial begin
        $display("シミュレータは上のコメントを見ない");
        $finish;
    end
endmodule

これが全構文です。Pythonの#もVHDLの--もLispスタイルもありません。//と/* ... */だけです。

どちらを使うか

//はほぼ毎回手が伸びる選択肢です。短く、誤って閉じ忘れることがなく、Verilogの書き方（1行1宣言、コメントを同じ行か隣の行に）に自然に馴染みます：

output reg [7:0] data,  // tx_serialから送り出すバイト
output reg       valid, // データ送信中は1
input  wire      ready  // 下流のコンシューマが受け入れ準備完了

/* ... */は主に2つの用途のためです。ファイル先頭の大きなヘッダブロックと、デバッグ中にコードの塊を一時的に無効化することです。後者は危険です。読み進めてください。

「ネスト不可」の罠

ブロックコメントはネストしません。すでにブロックコメントを含む領域をコメントアウトしようとすると、最初の*/が内側ではなく外側のブロックを閉じます：

/* 外側
   /* 内側 */    // <-- この */ が外側のコメントを閉じる
   パーサにとっては以下はソース内で生きている
*/

結果として、正しく見える行のどこかで予期しない構文エラーになります。

領域を無効化する必要があるときは、次のどちらかを優先してください：

すべての行に//をつける。 ほとんどのエディタはワンキーで実行できます。

プリプロセッサガードを使う：

`ifdef DISABLED
    // コンパイルされるべきでないコード
`endif

2つ目のパターンは、1つのファイルで複数のビルド設定を保持する方法でもあります。

合成プラグマ：コメントではないコメント

ベンダーツールは特別な形式のコメントを帯域外の指示として使います。シミュレータは依然として無視しますが、合成ツールは読み取ります：

// synthesis translate_off
initial begin
    $display("シミュレータ専用のセットアップ");
end
// synthesis translate_on

2つのプラグマは合成ツールに「この間のものはスキップせよ」と伝えます。正確な綴りはベンダーによって異なります（synthesis、synopsys、pragma、xilinxなど）。ツールのドキュメントを確認してください。知っておくべき点は、Verilogのコメントは時に「効いている」ということです。

ヘッダブロックの慣習

長く残るVerilogファイルは、ほぼ常にヘッダブロックで始まります。正確な形式はチームのポリシー次第ですが、典型的な例：

// -----------------------------------------------------------------------------
// Module      : uart_tx
// Description : 8-N-1 UART送信器。`valid`がアサートされたら`data`の
//               バイトを受け取り、`serial_out`に送り出す。
//               `baud_tick`は1ボー期間ごとに1パルス出す必要がある。
// Ports       : clk        - システムクロック
//               reset_n    - アクティブLowの同期reset
//               baud_tick  - 各ボー間隔で1サイクルのパルス
//               data       - 送信するバイト
//               valid      - 送信開始のためアサート
//               serial_out - FPGAから出る配線
//               busy       - フレーム送信中は1
// Author      : example@team
// Revision    : 2026-05-26 - 初版
// -----------------------------------------------------------------------------

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

要点は装飾ではありません。要点は、1年後にこのファイルを開く人（おそらくあなた自身）が、4行読めば、何をするか、何を期待し、何を生成するかが分かることです。その見返りはプロジェクトのサイズに比例します。

価値のあるインラインコメント

よくある間違いは、コードがすでに示している何をするかをコメントすることです：

// 悪い例 - コメントがコードを言い直しているだけ
count <= count + 1;   // countをインクリメント

// 良い例 - コメントがなぜこの行があるかを説明している
count <= count + 1;   // タイムスタンプ用のフリーランニングサイクルカウンタ

コメントが特に得意なのは、コード自身では示せないなぜを説明することです。風変わりなエンコーディングが従っている仕様のセクション、registerが見た目より1ビット広い理由、defaultケースが'0ではなく'xに設定されている理由。そこに頼ってください。明白なことはコードに任せましょう。

試してみる

下のブロックはすべてのコメント形式を含みます。実行してください。出力に驚きはないでしょうが、ファイル構造には注目してください：

// -----------------------------------------------------------------------------
// Module      : full_adder
// Description : 1ビットの全加算器。a, b, cinから`sum`と`cout`を出力する。
// -----------------------------------------------------------------------------

module full_adder(
    input  wire a,      // 1番目の加算ビット
    input  wire b,      // 2番目の加算ビット
    input  wire cin,    // 下位桁の加算器からのキャリーイン
    output wire sum,    // a XOR b XOR cin
    output wire cout    // (a AND b) OR (cin AND (a XOR b))
);
    /* 以下の2つの式は教科書通りの全加算器。
       sumは3入力のパリティ、cout は3入力の
       多数決。 */
    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通りの入力組み合わせを掃引する。
        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がサポートするすべてのコメント形式を見ました。残りのドキュメントは期待通りに使います。長いmoduleの先頭にヘッダブロック、ポートの隣に1行//、そして段落分の理由を残す必要があるときだけブロックコメントを使います。

よくある質問

Verilogでコメントはどう書くのですか？

Verilogはどちらもからの2つのコメントスタイルをサポートします。//は行末までのコメントを開始します。/* ... */は複数行のブロックを囲みます。マーカー間はすべてコンパイラが無視します。両スタイルとも合成可能・シミュレーション専用どちらのファイルでも等しく有効です。

Verilogコメントは合成されますか？

コメントはパース後には存在しません。合成ツールはシミュレータと同様に捨ててしまいます。唯一の例外は 合成プラグマ で、// synthesis translate_offのように特別な形式のコメントをベンダーツールがディレクティブとして認識します。プラグマ構文はツール固有で、標準Verilogの一部ではありません。

Verilogコメントはネスト可能ですか？

いいえ。これは/* ... */を含むブロックをコメントアウトしようとする初心者を引っかけます。最初の*/が外側のコメントを閉じてしまい、残りのブロックは生きたコードのままになります。各行に//を使うか、本当に大きな塊を無効化したい場合は\ifdef SOMETHING_FALSE/`endif`で囲んでください。

Verilogのヘッダコメントには何を含めるべきですか？

多くのチームはすべてのファイルの先頭に小さなヘッダを置きます。module名、1文の目的、ポート概要、著者/日付、リビジョン履歴。正確な形式はさまざまですが、重要なのはファイルを開いた人が本体を読まずに何をするものかわかることです。大きな設計では、すべてのポート宣言の横にsignalごとのコメントを追加します。