ソースファイルの先頭や、関数やクラスの「上」に、どういったコメントを書くか、ということは、組織や開発プロジェクトによってルール化されることも多い。
しかし、関数内部の処理の途中に書くようなコメントは、プログラマまかせになりがちだ。かといって、その書き方について、熱心な教育が行われているわけでもない。プログラマは、自らコメントの書き方を学ぶ必要がある。
「コメント論
」に書いたように、私が書いて欲しいと思うのは「見出しとしてのコメント」と「注釈としてのコメント」である。今回は、前者について、もう少し詳しく書いてみようと思う。
コードにも段落がある
通常、ソースコードには、いくつもの空行（改行だけの行）がある。プログラマは、コードの中に「区切り」のようなものが欲しくなって、そこに空行を入れるのだろう。
コードを区切りたいと思うのは、コード内の処理がいくつかの意味的な「まとまり」に分かれるからだ。
ある程度大きな「まとまり」は、関数などに分けるべきである。しかし、小さな「まとまり」は関数の中に残る。そういう「まとまり」と「まとまり」の間に、人は空行を入れるのだ（※１）。
コードのまとまりは、普通の文章で言えば「段落」のようなものである。場合によっては、複数の段落をまとめた「節」のようなものも出来ることがある。更に、節をまとめて、「章」ができることもあるだろう。
そうした階層的なまとまりを明確に区切って見せるために、例えばこんなコメントを使うこともある。
// ----------------------------------------
「線」を使うことで、空行よりも大きな単位での「区切り」を表現しようというわけだ。
段落に名前をつける
さて、コードに段落のような「まとまり」があるのであれば、そのまとまりに対して、名前をつけることが出来る。それが「見出しとしてのコメント」である。
「見出し」というからには、その処理の「まとまり」が、何をするものなのか簡潔に表さなければならない。長い文章ではなく、「ナントカ処理」とか、「○○を××する」というように、短く書くのがよい。
もちろん、ただ短かければよいというものでもない。一般的な書き方というものを規定することは難しいのだが、見出しというものが何のためにあるのか、ということを考えれば、自ずと分かってくるのではないかと思う。
見出しの効能
ソースを読む立場として、「見出しとしてのコメント」をなぜ書いて欲しいかといえば、それがない場合よりも、コードの全体像を把握しやすいからである。全体像を把握しやすいということは、読者が読みたい場所にたどり着くまでの時間が短くて済むということだ。
新聞を読むとき、見出しをざっと眺めて、興味のある記事が見つかったら本文を読む、という方法をとると思う。もし、新聞に見出しがなく、本文がびっしり書いてあったら、それがどんなに美しい文章であったとしても、「読みにくい」といわざるを得ないだろう。
ソースコードにおける「見出しとしてのコメント」にも、新聞の見出しと同じ効能がある。だからこそ、私は、どんなに美しいコードにも、「見出しとしてのコメント」を付加するよう求めるのだ。
プログラマには、初めて読むようなソースを緊急にデバッグ（不具合修正）しなければならないようなこともある。こんなとき、見出しとなるコメントがあるのとないのとでは、バグ（不具合の原因となる場所）にたどり着くまでの早さが圧倒的に違う。
あるいは、ソースレビュー（他の人の書いたソースコードのチェック）をしていて、仕様面で気になるような所だけを確認したいような場合もそうだ。読む側としては、見出しだけを拾い読みしながら、ソースをどんどん「スクロール」して、関係ないところは読み飛ばしたいのである。
「時間」のことを言うなら、コメントを書く時間がもったいないという人がいるかもしれない。しかし、１人のプログラマが書いたソースコードも、将来的には、何人もの人が、色々なシチュエーションで、何度も読むことになる。コメントを書くために要する僅かな時間は、読者がコードを読解するための時間を短縮して余りあるだろう。
どう書くか
要するに、「見出しとしてのコメント」は、読者がコードの全体像を把握するのを助けるように書け、ということだ。
そのためには、とにかく書き過ぎてはいけない。まず、「まとまり」に対する見出しなのだから、コードの毎行に書く必要はない。また、内容はあくまでも「見出し」、せいぜい「要約」だ。コードに書いてある処理をそのまま文章にしたような、細かいコメントも必要ない。
コメントの量が多すぎたり、内容が細かすぎたりすると視認性が悪くなり、その効果が薄れるからである。
上手い「見出し」を作るには、ある程度のセンスが必要だ。短く書くためには、苦労して言葉を選ばなけばならないこともあるだろう。それは、一般の文書で見出しを書くのと同じことである（※２）。文書作成が上手い人は、コメントが上手いというのは、そういうわけである。
※１
空行に限らず、インデント（字下げ）やブロック（Ｃ言語等では { ... } ）も、「まとまり」を作る区切りとしての意味を持つ。コメントを書く際に想定する「まとまり」は、あくまでも処理の「意味的なまとまり」であるべきだが、このような「コード上のまとまり」とも大いに関係する。例えば、条件分岐（if 文）や、ループ（for, while）の前にコメントを書けと言われることがあるのは、そういうわけだろう。
※２
「書かずに伝える 」も参照。もっとも、ソースコードを書く場合は、設計書の見出しを借用することもできるので、比較的楽かもしれない。もちろん、設計書の見出しが適切である前提だが。
■関連記事
・もっとコメント論 ～その１～ コメントとは何か
・もっとコメント論 ～その３～ 注釈としてのコメント
・もっとコメント論 ～その４～ システムの開発や保守のために
・もっとコメント論 ～その５～ コードが求めるコメント
筑摩書房 (2005/08/08)
売り上げランキング: 4,674
総論はすばらしいが・・・ 「わかる」とはどういうことか
解決v(^o^)
小学館 (2002/10)
売り上げランキング: 189,024
見出しだけ速く読んでも．．． TIMEを軽く感じられる「かもしれない」本 見出しが一番難しい
訳が最悪
