ソースコードのコメント率は20%を切ることが望ましい

大学の研究室の教官は昔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. ソースコードのコメント率を調べるには、コメント書うんたが便利。

Comments

1. Posted by 通りすがり   2007年09月13日 23:59

小野さんのおっしゃる主旨は理解できるし、また私自身も過剰なコメント付加などナンセンスそのものだと思うのだけど。

そもそも小野さんはSIerがやっているような種類の仕事のご経験がありますか？
一人でPerl書きだとか、あるいは開発者がメンテを７年間継続し続けるなどという理想状態ではなく、例えばJavaの文法も知らないような低スキルコーダ数十人が、Javaの詳細設計と称しひたすら意味不明なExcelシートを量産しつづける、地獄のような現場を見た事がありますか？(御社で役員をされていた方の現場の話ですが)

よりよい環境を獲得しえた人が、違う立場で動いている人達の経験則を笑うのはとても簡単な事です。
私はソフトウェア開発の方法に対し科学なり工学なりを求め続ける人間でして、コメントの分量を議論する際には、前提条件の提示が必須だと考えます。

2. Posted by επιστημη   2009年09月17日 06:14

> 例えばJavaの文法も知らないような低スキルコーダ数十人が...

そんな状況に対し山ほどのコメントが役に立つかというと疑わしいようにも思えるんですけど。

3. Posted by コメントは少なくあるべきだと私も思います   2010年10月31日 06:31

コメントは・・・とありますが、本当の趣旨はコメントの分量の議論では無く

「ソースは、コメント率が20%以下でもわかるように綺麗に書いて欲しい」

ただ、それだけ。