ここでいう「コメント」とは、プログラムのソースファイルの中に、日本語（や英語など）で書く説明のことである。コメントはプログラムの動作には関係ない。しかし、全く書かれていないソースコードは、読みにくいものだ。
というと、コメントはとにかく沢山書けばよいように思われるかもしれない。しかし、そういうものでもない。書くことによる弊害もあるからだ。
例えば、コメントに書いていることが「嘘」になる危険性だ。ソースを編集しているうちに、コードとコメントの内容が不一致になってしまうことはよくある。これは言うまでもなく、誤読の原因となる。
結局のところ、コメントは多過ぎても少なすぎてもよくない。そのあたりのバランス感覚を身に着けることが大事だろう。
★
関数の引数や戻り値などを説明するためのコメントの書き方は、プロジェクトなどでルール化されることも多い（※）。
しかし、関数の「本文」の処理の中にどのようなコメントをどの程度書くか、ということは、プログラマまかせになりがちである。このため、人によって、必要なコメントが無かったり、読みにくかったりすることになる。
処理内のコメントの付け方がルール化しにくいのは確かである。しかし、上手く書くコツのようなものはあるだろう。
ひとつには、処理のまとまりに対する「見出し」となるように書くことである。ちょうど、新聞や雑誌の見出しがそうであるように、それだけを読めば、そこにどんな処理が書いてあるのか、瞬時に把握できるようにするのだ。
もうひとつは文字通りの「注釈」である。処理の仕様が複雑な場合や、プログラムの書き方が止むを得ず不自然になってしまった場合など、そのままではコードが誤読される恐れがある場合には、コメントを書くようにしたい。
こうした、「見出し」や「注釈」を書くということは、プログラミングだけでなく、一般的な文書作成にも必要なことだろう。特に、プログラムの設計書を書くような場合には、このような能力は非常に重要となってくるのではないだろうか。
他にも、細かく言えば、変数の説明だとか、条件式の説明だとか、コメントを書くべきポイントはいくらかある。もし、コメントの書き方について意識したことのないというプログラマがいたら、これを期に、どのようなコメントが読みやすいのか、一度考えて欲しいのである。
※javadoc のようなツールでコメントを機械的に処理する場合には、ルールは厳密である。
■関連記事
・もっとコメント論 ～その１～ コメントとは何か
・もっとコメント論 ～その２～ 見出しとしてのコメント
・もっとコメント論 ～その３～ 注釈としてのコメント
・もっとコメント論 ～その４～ システムの開発や保守のために
・もっとコメント論 ～その５～ コードが求めるコメント
開発者のための実装系Webソースコードマガジン CodeZine（コードジン）傑作選 Vol.1
posted with amazlet
on 06.04.30
SE編集部
翔泳社 (2006/02/14)
翔泳社 (2006/02/14)
Write Great Code〈Vol.1〉ハードウェアを知り、ソフトウェアを書く
posted with amazlet
on 06.04.30
Randall Hyde 鵜飼 文敏 まつもと ゆきひろ 後藤 正徳 トップスタジオ
毎日コミュニケーションズ (2005/12)
毎日コミュニケーションズ (2005/12)