HDLのコメントの重要性

HDLのコメントの重要性

 HDLにはコメントを書く事ができます。コメントこそ、エンジニアの個性が出るところです。

 会社でコメントの書き方をルール化しているところもあります。私がコメントで心がけているのは、半年後の自分に理解できるようにする。という事です。

 ソフトウェアでもハードウェアでも、半年前に自分が作った物をメンテナンスする。という機会は多くあります。しかし、その時、「これ、本当に自分が書いたのか?」というぐらい覚えていないものです。よく、こんな回路を思いついたな。とか、半年前の自分は天才だ。と思う事もあるぐらい、本当に半年経てば自分の仕事は忘れてしまいます。

コメントは書くな

 コメント率という言葉があります。ソースコードの中でどの程度コメントを記載しているか。という割合なのですが、一般的にはコメント率は低い方が良いとされています。

 おそらく、その理由はコメントは仕様書では無いので、仕様書がきちんと書かれていれば、コメントは不要だ。というのと、コメントが無くてもわかるようなソースコードを書きなさい。という事からだと思います。

 デジタル回路設計はVHDLやVerilogなどのHDLで記述することが多くなりましたが、回路図で設計していた頃はコメントなど書くスペースがなく、日本語対応の回路図CADも少ない時代でした。そんな時代の名残だとも考えられます。

コメントを書け

 私の経験からですが、お客様からソースコードの開示要求付きで仕事をする場合、要求事項の中にコメント率が入っている場合があります。その場合にはコメント率は高くするよう要求されます。つまり、納品するソースコードにはコメントを多く記載しなさい。でなければ、納品を認めない。という事です。

 これは、「納品」という事は他者が書いたソースコードを担当者が読む。という事があるので、コメントが多く無いとやってられない! という事だと思います。

どっちが正解?

 はっきり言って、この2つの例は矛盾しています。「書け」と「書くな」ですから。しかし、私には「書くな」の理由付けが理解できません。コメントが無くてもわかりやすく書きなさい。というのは、大前提です。変数名にhogeとか、A,B,C,Dといった意味の無い文字列を使って、コメントで説明する。という書き方は論外です。

 もし、コメントが多すぎる。不要だ。というのであれば、ソースコードの中からコメントを削除するスクリプトを組んで一緒に納品します。不要なら消してください。という事です。

 時間は元に戻す事ができません。半年前にコメントが無かったら、半年後にコメントを追加するのはかなりの労力を要します。どんなくだらないコメントでも書くようにします。不要なら、削除して読めば良いのです。

 たとえば、私はソースコードのヘッダーに天気を書く事もあります。ソースコードに全く関係ありません。しかし、人間の記憶は何がきっかけで思い出すのかわかりません。洪水だったり、雷雨だったり、日付と天気で思い出す事もあります。とにかく、半年後の自分に「思い出してくれ!」というヒントをなるべく残すようにしています。

 今時、フロッピーディスクでプロジェクトを管理している訳もなく、ソースコードがコメントで倍の容量になったとして、誰が困るのでしょうか?

英語?日本語?

 コメントはできる限り書きましょう。英語でも日本語でも構いません。誰かにソースコードを説明しているつもりで書いてください。仕様書が完璧なら不要。と思ってはいけません。仕様書もソースコードも両方で200%になるようにコメントを残せば、半年後に自分がメンテナンスする時に、必ず救われる事でしょう。

 ただし、困った事がひとつだけあります。日本語に対応していない開発環境があります。特にシミュレータのエディターは日本語に対応していないものが多く、日本語のコメントは文字化けになってしまいます。

 文字が化けるだけなら良いのですが、その状態で「保存」してしまうと、二度と日本語が表示できなくなるケースがあります。

 私はエディターは使い慣れた日本語対応のものを使うようにしています。最近の統合開発環境のエディターは非常に便利なのですが、日本語が化けてしまっては意味がありません。統合開発環境ではエディターを指定できる場合がありますので、外部エディターを設定するのが良いと思います。

 もう一つ、コメントで履歴も残してほしい。という事です。ファイルの履歴を別ファイルで管理していると、履歴ファイルの更新を忘れがちです。最低でもバージョン番号と日付はコメントで残すようにしましょう。