コメントは量じゃない

プログラムの理解しやすさの指標の一つに「コメントの多さ」を挙げる人がいます．「プログラムをわかりやすくするにはコードにたくさんのコメントをつけろ」というわけです．もっと極端に「コメントのたくさんあるプログラムはわかりやすい」という人までいます．これはとんでもない間違いです．

以下のプログラムを例としてあげます．言語はperlですが，使っている言語は問題の本質ではありません．

#!/usr/bin/perl -w
use strict;

my $file=""; # 初期化
my @stat=stat "sam.txt";
my $fsize=$stat[7]; # ファイルサイズの取得
open FILE,"sam.txt"; # ファイルをオープンする
read FILE,$file,$fsize; # ファイルの読み込み
close FILE; # ファイルのクローズ
print $file; # 出力

私はこのプログラムを非常にわかりにくいと思います．理由はコメントが少ないからではありません．コメントがコメントの体をなしていないからです．

例えば，open FILE,"sam.txt";が「ファイルsam.txtをハンドルFILEとしてオープンする」と「サーバsam.txtにポートFILEで接続」との二通りに解釈できるのなら，「ファイルをオープンする」というコメントには意味があります．しかし，open FILE,"sam.txt";は「ファイルをオープンする」としか解釈できないのであれば，このコメントには意味がありません．上記プログラムは，言うならばこう書いていると同じです．

#!/usr/bin/perl -w
use strict;

my $file=""; # my $file="";
my @stat=stat "sam.txt";
my $fsize=$stat[7]; # my $fsize=$stat[7];
open FILE,"sam.txt"; # open FILE,"sam.txt";
read FILE,$file,$fsize; # read FILE,$file,$fsize;
close FILE; # close FILE;
print $file; # print $file;

コードとまったく同じ内容のコメントををつけて，大きさだけが２倍になったプログラムはわかりやすいのでしょうか．そんなはずはありません．コメントはプログラム言語を日本語に直したものではないのです．

もちろん，コメントは全くいらないと言うのではありません．コメントは必要です．コードに書いてあることと同じことをもう一度日本語で書くために必要なのではなく，コードにはかけないことを書いておくために必要なのです．

プログラムの理解を助けるコメントと，理解を妨げるコメントがあるのです．理解を妨げるコメントは，たくさんあればあるほどわからなくなります．つまり「コメントがたくさんあるプログラムはわかりやすい」というのは暴言もいいところなのです．

不味い料理はどれだけたくさんあっても美味くはなりません．逆に，たくさんある不味い料理ほど不味いものはありません．もっと言うなら，美味い料理もたくさんあると飽きてきます．飽きた料理もやっぱり不味いのです．コメントも同じです．

ちなみに，私なら上記プログラムにはこういうコメントをつけます．

#!/usr/bin/perl -w
use strict;

my $file="";
my @stat=stat "sam.txt";
my $fsize=$stat[7]; # statコマンドでは返却値（配列）7番目の要素にファイルのサイズが入る
open FILE,"sam.txt"; # sam.txtは社内のサムさんの一覧．
read FILE,$file,$fsize;
  # sam.txtの内容を“改行も含めて”$fileに読込む．
  # statコマンドでファイルサイズを取得する方法を覚えたのでreadで読み込んでみた．
  # $file.=$_ foreach <FILE>;でも同じことができる．
close FILE;
print $file;