悪態のプログラマさんの「もっとコメント論」の記事を見て、ひさびさにコメントに関する記事でも書いてみようかと思います。

以前「省コメントのススメ」という記事を書きました。コメントを書きまくる前に、コメント無しでも分かるようなソースを書きましょうという主旨で書いたつもりです。

しかし、コメントは少なければ少ないほど良いと思っているわけでは決してありません。本当に必要なコメントを書くべきで、むやみやたらに書くものではないという意味です。

例えば、私は次のようなセパレータコメントを使います。

////////////////////////////////////////////////////
/// @breif セパレータコメントクラス
///
/// プログラムを読みやすくするための罫線のような役割のコメント  
class SeparatorComment : public Comment {
{
  ...
}

セパレータコメントと呼んでいるのは、「//////」とスラッシュが罫線のようになっている部分のことです。このようなセパレータは賛否両論あって無駄だという人もいます。コーディング規約で禁止しているものも見かけたことさえあります。 確かに最近のエディタでは、コメント部分の色分けもされますし、関数単位の検索も用意なため、派手なセパレータは要らないだろうというのも分かります。私もあまりに派手にデコレートされたソースは敬遠したくなります。しかし、要所要所に入ったセパレータコメントは可読性を向上させる効果があると思っています。適切な段組のようなもので、いわゆる「見出し」の一種ということになるでしょうか。 このようなソースコードの整形は、コメントでしかできないものですので、コードの処理を理解する上では直接役に立たないとしても決して無駄とは言えないでしょう。

上記のセパレータコメントに関しては私の意見ですが、反対意見をお持ちの方もおられるでしょう。その他のコメントに関しても、ひとつひとつ取り上げれば、人によって賛否両論あると思います。とはいえ、正解がないからといってどんなコメントでも良いというものでもありません。

「何のためにコメントを書くのか」

まずはこれを考えることが肝心です。英語コメントなどはコーディング規約だからというのも理由のひとつかもしれませんが、そのコーディング規約に本当に適切かということに立ち返って考えるべきです。同じようなモジュールに見えても、誰がどのように開発・保守・再利用されるのかによって、適切なコメントの基準というのは変わってきます。

統一感というのも可読性を考えると重要なので、コメントの書き方もある程度コーディング規約で統一することも必要かもしれません。しかし、ただルールだからといって書いていたのでは、適切なコメントを書くことはできないでしょう。

コメントは考え出すと宗教論になりがちですが、「どう書くのか」にこだわるのではなく「何のために書くのか」を考えることが先決でしょう。

【関連記事】
・省コメントのススメ
・英語のコメント