« 「隣同士なのになぜ話さないのか」 | トップページ | 複合キーの必要性はなし? »

2006年9月 5日 (火)

「コメント率50%」の謎

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

小野和俊のブログ:ソースコードのコメント率は20%を切ることが望ましい

少なくとも、「いまどきのプログラミング言語」を前提にしますと、「コメント率50%」はほとんど「逐語訳」に近いわけでして。確かに異常な数字だと思いますね。

「コメント率50%」がどこから来たのか、理由をいくつか考えてみました。

---

1) 昔の習慣を引きずっている

「昔の言語」-FORTRANやCOBOL-の場合、そもそも、わかりやすくコードを記述するのが不可能だったりします。変数やプログラムの名前の長さも相当制約されており、多くは"PG010001"といった、「意味不明」の名前が付けられていたりします(今どきの言語を使っているのに、今だにこういった名前を好んで使う人もいますが)。

これらの「暗号」を解読するには、ほぼソース1行あたり1行くらいの割合で、「平文」が必要になります。

2) 「英語だとわかりません」

ソースコードは英語で書かれています。英語というより、「英単語」程度なんですけどね。しかし、これでも「日本語訳が欲しい」という向きがあるようです。

3) 「プログラムが読めません」

ちょっと信じられませんが、SI業界には、「プログラムを読めないプログラマ」は存在するらしいです。コメントで解決する問題ではないと思いますが。

---

コメントを多くつけると、ソースコードがわかりやすくなる、というのは幻想にすぎないと思います。確かに、「的確なコメント」がついていれば、幾分、わかりやすくなることはあるかもしれません。が、「的確なコメント」が出来るなら、「的確なソースコード」を書く能力はあるでしょうし、結局、わかりにくいコードに、わかりにくいコメントをつけて、さらに解りづらくしている、というのが私の印象です。

|

« 「隣同士なのになぜ話さないのか」 | トップページ | 複合キーの必要性はなし? »

コメント

こんばんは!
コメントについては意見も分かれますが、私は分かるならそれで良いと考えています。多かろうが少なかろうが分からなければ駄目かなと。

投稿: 手文庫 | 2006年9月 6日 (水) 01時37分

手文庫さん、コメントありがとうございます。
>私は分かるならそれで良いと考えています。
そのとおりですね。
ただ、この問題の根っこには、
「ソースを読んで評価できる人間がいない」
というのがありそうです。
「ソースが読めないソフトウエア・エンジニア」は、
「図面の読めない建築家」「楽譜の読めない音楽家」
のようなものかな、と思っています。

投稿: ron | 2006年9月 6日 (水) 23時29分

いや、謎でもなんでもない。
java.lang.* のコメントについては、javadoc しか読まない人向けのコメントが満載なので、どうしても多くなる。
ソースの一部が、ドキュメントを兼ねているわけだから。

元の「20% 以内」ってのは、ソースを読めるように書けば、コメントなんて要らないでしょう、ということなのだから、
ソースを読まない人向けのコメントを含めちゃ駄目だよね。

# 結構前の記事に対するコメントで恐縮ですが m(_ _)m

投稿: jimsie | 2009年6月 9日 (火) 22時04分

> ソースを読まない人向けのコメントを含めちゃ駄目だよね。

そのとおりなのですが。

ここのエントリでいう「コメント」は、ドキュメンテーション・コメントのことではなく、通常の(といっていいかわかりませんが、ソース読める人向けの)コメントの意で使っています。

対象としてる「プログラム」は、公開 API を大量にもつ、java.lang.* のような汎用ライブラリではなく、SIer で作るような、業務アプリケーション・プログラムの類ですね。

コメントいだたいて、このエントリを読み返してみましたが、用語の使い方が、かなり適当でしたね。すみません。我ながら、文書力ないなあ。

投稿: ron | 2009年6月13日 (土) 00時17分

> すみません。我ながら、文書力ないなあ。
いや、そんなことないですよ。ぼくはタイトルにしかコメントしてない。というよりは、トラックバック先の

>> 1. Java 5.0 の CoreAPI の場合、最も典型的な公開されるAPIの java.lang.* パッケージは50%オーバーで
に対するコメントか。

# ぼくのコメントの表現力が無い、と m(_ _)m

そもそも、元記事の「基本的に、コメントを多く書きすぎるのは良くない、と思うが、こういう場合は仕方ない」という内容に Yes/No を示す以外に、コメントをつける見方として、

†何故、20% や 30% ではなく、50% が基準なのか
†何故、コメントが少ないと、品質が低いと判断されるのか
†品質が低いコードは、コメントが少ないのか
†何故、昔はコメントが多くないと駄目だったのか
†昔の思い出

等々、いろんな視点はあるんだと思うんですよね。
"50%" という値は別にして、「コメントが多いことが正しいとされるケースの幾つか」という意味での記載には同意です。

投稿: jimsie | 2009年6月14日 (日) 08時53分

コメントを書く



(ウェブ上には掲載しません)


コメントは記事投稿者が公開するまで表示されません。



« 「隣同士なのになぜ話さないのか」 | トップページ | 複合キーの必要性はなし? »