大学の研究室の教官は昔NTT研究所の所長をされていた苗村先生という人で(と言いつつ私は大学の研究室にほとんど顔を出していなかったのだけれど)、彼の発言のうち印象に残っているものの一つとして、昔はソースコードのコメント率が50%を切るものはドキュメント不足で品質が低いものとされた、という内容のものがあった。

当時野村総研のアルバイトで毎日 Perl でせっせとナレッジマネジメントシステムを設計し構築していた私にとって50%という数字は大変驚くべき数値で、そんなにコメントばかり書いているなんてなんと非生産的な、というのが正直な感想で、百歩譲って、大規模な開発の場合に求められる必要悪としてのコミュニケーションコストか - などと、まあ色々考えたものである。その時の私のソースコードのコメント率はおそらく5%を切っていたと思う (良い意味でも悪い意味でも)。私が関わっていたプロジェクト全体でプログラマーは私一人で、ソースコードの行数は５万行程のプロジェクトだった。

今、改めて考えて、どのような言語であってもどのようなコーディング規約であっても、私はソースコードのコメント率は原則20%を切ることが望ましいと思う。可読性の意味でもメンテナビリティの意味でも、開発生産性の意味でも。私が考えるに、本来コンピュータが読むためのものであるソースコードに人が読むためのコメントを付け加えなければならないのは、次の２通りの場合だけである。

1.公開されるAPI
APIやソースコードそのものが公開される場合、利用者は不特定多数となり、利用者のスキルにもばらつきが出て、おもんぱかってもらえないケースが出てくるし、「書式」が整えられていないと不愉快に感じたり不安に感じたりする人もでてくる。だから公開されるAPIには丁寧で、時として過剰なコメントが必要となる。例えばクラス TestClass のデフォルトコンストラクタには、「これはクラス TestClass のデフォルトコンストラクタです。引数はありません。その他のコンストラクタとしては、TestCass(String arg1)とTestClass(String arg1 String arg2)があります。」というようなコメントが付加される。これらはコメントなど書かなくても本来コンストラクタのシグニチャからわかることだが、APIを公開する場合にはこうしたコメントが求められることが多い。この種のコメントで、実装とコメントの同期が取れてなかったりすると混乱の原因となって非常に良くない。

2.トリッキーな実装
ソースを読んだだけではすぐにわからないようなアルゴリズムを採用している場合や、使用しているライブラリのバグ回避のための特殊な処理を行っている場合、または他の人が見たときや自分が数年後に見た時に「なぜここでこんなことを？」と感じる可能性がある場合にはソースコードにコメントを追加するべきだ。これは言わばトリッキーな実装である。こういうコードはできる限り回避すべきで、最悪なのはクラスやメソッドの命名や切り分けがおざなりで、それをコメントで補っている場合である。例えば「このメソッドは(実は)XXという動作をします」とか、「(コピぺしてきたのでほとんどの部分は無視してほしいところですが)ここでやろうとしているのはこういう処理です」という類のコメント。

アプレッソではパッケージ製品としてDataSpiderを約７年間開発・メンテナンスしていて、現在の最新版でソースコードの分量は120万行ほど。 ソースコード中のコメント率は約15%で、期間・規模ともそこそこの規模のものだが、上記ポリシーで困ったことはほとんどない。これまで見たコメントのうち、唯一上記の２パターンに該当しなかったのは、あまり使われないモジュールなのだけれども超特急でつくらなければならなかったモジュールで、「このクラスは急いで作ったのでグチャグチャです。現在要求されている機能の範囲で安定して動作しますが、機能追加の際にはリファクタリングせずに作り直すことをお勧めします」というコメントだったのだけれど、これはこれで率直で役に立つコメントだった(そして実際、私たちはそのクラスを破棄して作り直した)。

先日、とあるSIerの方とお話した時に、上記のような考えで、ソースコード中のコメント率は２０％を切るべき、コメントなど書かなくてもわかるようなコードこそ美しい、という話をしたところ、怪訝な顔をされてしまったことがあった。彼にはちゃんと理由を説明して納得してもらったのだけれども、もしコメント率50%と主張している人がいたら、もう一度その必要性を振り返って考えてみてもよいのではないだろうか。

参考までに:
1. Java 5.0 の CoreAPI の場合、最も典型的な公開されるAPIの java.lang.* パッケージは50%オーバーで、com.sun から始まる Internal API は20%未満。理想的な数字だと思う。
2. ソースコードのコメント率を調べるには、コメント書うんたが便利。