もっとコメント論　～その４～　システムの開発や保守のために

これまで、「見出しとしてのコメント」、「注釈としてのコメント」について考えた。純粋にソースコードを完成させるという意味では、これらが上手く書ければ十分だろう。

ただし、システム開発という仕事の中では、更に、他の情報が求められる場合がある。そういった付加的なコメントの用途についても、いくつか書いておこうと思う。

ログとしてのコメント

ソースコードを変更した時、変更前のコードをコメントとして残しておくことがある。いわゆる「コメントアウト」である。

システムの保守をしていると、コードの変更履歴が知りたくなる場合がある（※１）。そのような事態を想定して、過去のコードを消さずに残しておくわけである。

このような場合、修正した日時や理由などを合わせて書いておけば、有益な情報となるだろう。いわば「ログとしてのコメント」である（※２）。

実は、この「コメントアウト」を残すことは、私はあまり好きではない。古いコードが残っていると、誤読の原因にもなるし、GREP（文字列検索）の邪魔にもなる。変更の履歴については、CVS や VSS などのソース管理用のソフトを使って管理したほうがよいだろう。

とはいえ、常にそういった管理ソフトが使えるわけでもなく、「ログとしてのコメント」を全面的に否定することもできない。

リンクとしてのコメント

ソースコードには、このようなコメントを見かけることがある。

　// [不具合票 No.00123] ××問題の修正
システムで発生したバグを、「不具合票」という書類で管理しているのだろう。コードの修正についての詳細な情報については、不具合票の No.00123 を参照せよ、というわけだ。

ここでは、書類の番号と、コードの修正箇所を「紐付ける」ために、コメントが利用されている。つまり、「リンクとしてのコメント」である。

このようなコメントも、システムの保守をする上で、有用な情報になる場合がある。過去の修正履歴を残すという意味では、「コメントアウト」と同じ用途といえるかもしれないが、「コメントアウト」ほど邪魔にはならないだろう。

覚え書きとしてのコメント

このようなコメントもある。

　// TODO: ××関数が完成したら、ここで呼び出すこと

「××関数」を呼び出す処理を書きたいのに、その関数がまだ出来ていないのだろう。後で書くのを忘れないように、メモしているのだ。

もちろん、こうした「TODO コメント」は、不要になったら消してしまうべきものだ。残っていたとしたら、「やるべきこと」をまだやっていないか、コメントを消し忘れているということになる。折をみて「TODO:」という文字を検索し、チェックすることも必要である（※３）。

多くの場合、「TODO コメント」の「読者」は自分自身なので、書き方については、それほど気にすることはないだろう。

★

ソースコードをひとつの完成した「製品」あるいは「作品」としてみた場合、今回挙げたようなコメントは、必要のないものだろう。あくまでも、システムの開発や保守といった、業務上の都合で付加するものである。

しかし、やはり、読者のために書くものだということには違いはない。読者が「修正前のコード」を必要とするからこそ、コメントアウトして残すのである。逆に必要とされていない場合は、残す必要はない。

続く

応援のクリックお願いします →

※１
「ログ」については、「ログとしてのメール」も参照。

※２
例えば、「デグレ」の調査をするような場合である。デグレ（デグレード）とは、プログラムを変更（改良、修正）したために、それまでうまく動いていたものが動かなくなるようなこと。いわば、「プログラムの改悪」。

※３
Visual Studio .NET や Eclipse といった最近の開発環境では、こうした「TODOコメント」を一覧表示する機能があって、便利だ。