コメントの重要性

いつか何かの記事でちょこっと触れた気がしますが、今回は若干本格的に。

自分が書いたソースコードを他人に理解してもらううえで最も重要なのは、やはり適度なコメントの記述だと私は思うのです。
「適度に」というのは若干あいまいな表現かもしれませんが、それは即ち「他人が関数名・引数名その他を見て、瞬時にその内容が分かりそう」なものでなければ、ということです。
では、３つの例をあげて説明していきます。（例の中の「GetPingdly()」は、関数内で定義されているサーバーにpingを送信し、それが帰ってくるまでの時間を計測、それを戻り値とする関数とします）

まずは１つ目。
------------------------------
void main() //戻り値を返さない関数main、エントリポイント
{
Console.WriteLine("●●●●");//コンソール上に●●●●と表示する
Console.Beep();//ビープ音を鳴らす
Console.WriteLine("△▽△▽");//コンソール上に△▽△▽と表示する
Thread.Sleep(3000);//3000ミリ秒の間動作を休止する
Console.WriteLine(GetPingdly());//pingを送信し、それが帰ってくるまでの時間を計測し表示する
}
------------------------------
明らかにやりすぎです。プログラム初心者向けにソースコードを書くのであれば、ここまでコメントしてもいいかもしれませんが・・・

それでは２つ目。
------------------------------
void main()
{
Console.WriteLine("●●●●");
Console.Beep();
Console.WriteLine("△▽△▽");
Thread.Sleep(3000);
Console.WriteLine(GetPingdly());
}
------------------------------
仲間内で、かつ関数GetPingdlyの存在がはっきりと認知されている場合はこれでもいいかも知れません。
今回はプログラムの内容が簡単すぎるので、「これで十分」という人もいるとは思いますが、ここでDirectXの描画やらIronPythonスクリプトの読み込みやら・・・色々面倒なものがかかわってくると、これで分かってもらえる確率は低くなってくるでしょう。まして赤の他人に公開する複雑なコードがこんな状態では、完全に内容を理解してくれる人は殆どいないも同然の状態になるでしょう。

そこで３つ目。
------------------------------
void main()
{
Console.WriteLine("●●●●");
Console.Beep();
Console.WriteLine("△▽△▽");
Thread.Sleep(3000);
Console.WriteLine(GetPingdly());//pingを送信し、それが帰ってくるまでの時間を計測し表示する
}
------------------------------
自作した関数GetPingdlyにのみコメントをつけているので、①に比べて非常に（コメント的な意味で）すっきりとまとまっています。また、この状態であればGetPingdlyの存在を認知していない人でもその関数の内容を把握できるため、「他人が見てわかるソースコード」でもあるわけですね。
このようなコメントの記述方法だと、②の最後に触れたように「面倒なもの」がかかわってきた場合でも「他人に分かりやすい」ソースコードになるわけです。また、自分が書いたソースコードを後から見返すときにも、コードの内容を一目でつかみやすく、大変便利になります。


ちなみに、③の方法を、「DLLImportを多用するソースコード」に使うと・・・
場合によっては、コードの量が３～４倍になってしまいます（＾＾；
VC#だと、summaryの部分はまとめて折りたためるので・・・ある程度は良さそうなんですがね（ﾎﾝﾄｶｵｲ

2009.9.3 AM10:52 一部表記を修正しました。指摘してくださった方ありがとうございます。