「ソースがすべてを物語る」
プログラマはときどきこんな風にうそぶくことがある。たいていは誰かが彼の書いた ソースプログラムに対して、 「コメントが少ない」とか「ドキュメントがないのか」とか文句をつけたときである。
いくらコメントをつけたとしても肝心のプログラムが間違ってたら何にもならないさ。 オレの書いたこのプログラムを読んでから文句を言ってくれよ。美しいプログラムだろう？ コメントやドキュメントなんてだるくて書けないさ。…プログラマはこんな思いをこめて一言つぶやく。
「ソースがすべてを物語る」
＊ ＊ ＊
もちろんここでいうソース（あるいはソースプログラム）というのは Ｃ言語やPascalやFORTRANといったプログラミング言語で書かれたプログラムのことを言う。 プログラマが書いたソースをコンパイラにかけ、 出てきたオブジェクトプログラムをリンカにかければ実際に動作する実行ファイルができあがるものだ。
コメントはプログラム中に書かれる注釈で、プログラムの実行にはまったく影響をおよぼさないが、 人間がプログラムを読むときの助けになるものである。ドキュメントは仕様書、マニュアルの類である。 日本語や英語で書かれ、プログラムの動作や使い方について書かれている。
＊ ＊ ＊
私も仕事でプログラム書きをする関係から、プログラマが、
「ソースがすべてを物語る」
のセリフを言いたくなる気持ちはよくわかる。
ちょっと腕に覚えのあるプログラマは誇りをもってプログラムを書いているのだ。 コメント（注釈）だとかドキュメント（文書）を書くことよりは ソースプログラム本体を書くことの方がずっと挑戦的な問題のように感じられるのだ。
しかし、この、
「ソースがすべてを物語る」
というセリフは正確ではない、と最近考えるようになった。私が考えついた新しい格言？はこうだ。
「ソースはすべてを知っている、けれども語ってくれるとは限らない」
これの方が真実に近い。
ソースプログラムには、コンパイラがオブジェクトプログラムを作成するために必要な情報がすべて 盛り込まれている。そうでなければコンパイルはできない。どういう関数が用意されていて、 どういう変数が用意されていて、どういう順番で何を実行するのか。 その情報はすべてソースプログラムに書かれている。それを、
「ソースはすべてを知っている」
と擬人的に表現しても悪くはないだろう。
コンピュータがプログラムを読む分にはそれだけでよい。 コンピュータはプログラムの各部分の「意味」を知らなくても動くことができるからだ。
けれども、人間は違う。プログラムを理解するためには、 読んでいる最中にひっきりなしにわいてくる疑問を解決しなければならない。 「なぜここでreturnしてるの？」とか、「なぜこんな変数がいるの？」 とかいった疑問である。時には、「そもそもここらへんでは何をやっているのだ？」 などというアバウトな疑問が浮かんでくるものである。 人間はコンピュータではない。機械的にソースプログラムの頭から順番に読んでいって、 「ふむふむ、ふむ。わかった」 と理解できるものではない。
ソースプログラムとしては表現しにくい、それでいて大切な情報。 それはプログラムの字面にかくされた「意味」であり、それを書いたプログラマの「意図」である。 人間がソースを読むというのはこの「意味」や「意図」を読みとることにほかならないのである。 プログラムの字面として表現しにくい情報がある。それをまた擬人的に、
「ソースはすべてを語ってくれるとは限らない」
と言うことをお許し願えるだろうか。ソースが自発的に人間に語りかけてくれる場合は少ない。
＊ ＊ ＊
例によって、"The Elements of Programming Style" からの格言を引用してみよう。 手厳しいのがあった。
Don't comment bad code -- rewrite it.
（ひどいプログラムにはコメントつけなどするな。書き直せ。）
これは確かに正しい。けれどもヘタなプログラマにこれをやられてしまうと 破壊的な事態を招くことがある。ヘタなプログラマであってもせめてコメントに 「ボクはこういうことをしたかったんデス」と書き残してあれば、 誰かがしりぬぐいできるかもしれないではないか。
趣味のプログラムならいざ知らず、仕事で作るプログラムにコメントが少なすぎたり ドキュメントがなかったりするのは、単純にプログラマの怠慢であることが多い。
＊ ＊ ＊
「ソースがすべてを物語るさ」
とうそぶいて、コメントつけをさぼったりドキュメント書きをしぶったりする若いプログラマは結構多い。 私は彼らに、
「ソースはすべてを知っている、けれども語ってくれるとは限らない」
という自家製の格言を伝え、
「すべてを物語るようなプログラムを書いてください」
と言うことにしている。自分自身への教訓も含めながら。
(Oh!PC、1990年6月20日)