プログラムの「コメント」活用方法のアラカルト
プログラムを書く際に、「どのようなプログラムなのか？」を記述しているのが、「コメント」ですが、いったい何を書いているのでしょうか。
「そもそもコメントの書き方って決まりがあるの？」
いろいろな疑問が湧いてきますが、コメントのアラカルトについて見ていきたいと思います。
コメントの「もう一つの役割」とは？
プログラム内のコメントには、「ドキュメント作成」を目的としているものが数多く見受けられます。
「あれ？どのような言語でも似たようなコメントだな。」
と思われた方も多いのではないでしょうか。
プログラムには「〜DOC」という仕組みを利用した書き方が一般的となってきていて、例えば、Javaであれば「JavaDoc」という仕組みを使い、プログラムに埋め込んだソースコードから仕様書を作成することができます。
JavaDocはJDKに付属しているため、すぐに利用できるという手軽さからJavaプログラマに広く普及しています。
他にも「JSDoc<」「RDoc」など、言語ごとにさまざまなドキュメント・仕様書作成ツールが用意されています。 /p>
例えば、「JavaDoc」では、
/**
* 純粋にhogeるためのクラスです.
*
* @version 1.3
* @author hogeo
*/
public class hoge {
/**
* 単純なhogeを表示します。
* @param name 名前
*/
public void simpleHoge(){
Sytem.out.println( name + "さん！hoge!!");
}
}
のように、@の後ろに必要な情報を記述していきます。
コメントを書いた時に気をつけたいことは、プログラムを修正した時に、修正内容を反映させることです。
プログラムの内容とコメントの内容が異なっていると、他の人が見た時に混乱してしまう元になり、そもそもコメントの意味自体が無くなってしまいます。
そのような理由から、「そもそもコメントは書かなくてもいい」という意見もありますが、コメントが無くてもわかるようなプログラムを書くことは簡単ではありません。
実務上でも仕様書を円滑に作成するためにコーディングルールとして、コメントを付加することが義務付けられていることもあります。
それはさておき、「何をコメントに書くのか？」は大切なポイントです。
中には「ここはテストに時間がかかりそうだけど、他の実装もあるし、面倒くさいな〜」
と言った「ただの愚痴」としか捉えられないようなコメントがあったりします。
他にも「ここは後で修正」という文言がある場合「いつの時点から」という情報が無いと、修正が必要な箇所を時系列で把握することが難しくなりますので、「コメントを付記した日時」を書いておく方が良いでしょう。
コメントには仕様書作成に利用される「プロダクトコメント」と開発時に一時的に利用される「テンポラリコメント」があります。
完成品に「テンポラリコメント」が残っていると、レビュー時に「あれ？このプログラム完成してるの？」となってしまいますので、テンポラリコメントとわかるように「temp:コメント」のように書いておくことで、テンポラリコメントをソースコードから探しやすくなります。
コメントの私物化事例？
プログラマはある意味「特殊な」人たちなので、そのコメントもバラエティに富んだものがたくさんあります。
〜その１〜
例えば、
/* これから会議だから終わったら、直すつもり、だけど、その後飲み会だから忘れているかも。 もしこのコメントが残っていたら、誰か教えてください。written by hoge */
自分で書いたコードの管理は他人に委ねないようにしようという気は毛頭無さげですね・・・
〜その２〜
自分の事情もコメントにしてしまって、
//来月子供が生まれるので、基本残業はしたく無いので、このコードに御用のある人は定時までにご連絡ください。
と書いている人も。
〜その３〜
お得情報を盛り込んで、コメントの正しい感を醸し出しているけれども・・・
//2月中は、食堂のご飯がおかわりし放題です！！
なんて、ことを書いている人も。
〜その４〜
中には「どうしたらいいの？」というコメントに出会うことも
//現在のところ問題なく動いています。「現在のところ」
ということは、たまに動かなくなる？・・・
〜その５〜
もうすぐ・・・
//引き継ぎにあまり時間が無さそうなので、わからない部分があれば、コードを隅から隅まで読み解いてください。
「読み解く・・・」そんなに難解なコードなのか。
こんなコメントは巷にたくさんあるそうです。
人情を感じるコメントが巷のプログラムには、たくさん溢れていそうですね。