ソフトウェア工学について その3(3) Whyの視点でコメントを記述する

コーディングをするとき、コメントを書くことは必要に応じて行われるが、コメントにはセンスが必要だと思う。
たとえば、コードを読めばわかるようなコメントというのは私の意見としてはうっとおしいと感じる。
よくいわれることであるが、コメントの鉄則は「Why」の視点に立って書くことが必要である。
Whyの視点に立つと、コメントはどう変わるのだろうか。

たとえば以下のプログラムを見てほしい。
何をしているのかがすぐにわかるだろうか。

リスト1 void main() {   // 変数Aに"string"を代入   char  a[]  = "string";   //入力文字格納用   char  b[100];   //posを0で初期化   int       pos=0;   //rをtrueで初期化   bool  r  = true;   // 入力した文字を変数bに代入   int result = scanf("%s",&b);     // aのpos番目が0以外  かつ  bのpos番目が0以外の間繰り返し   while( a[pos] != 0 && b[pos] != 0 ){     // もしもaのpos番目とbのpos番目が違うならば     if( a[pos] != b[pos] ){       // rにfalseを代入       r = false;       // ループを抜ける       break;     }     // posを1増やす     pos++;   }   // rの内容を表示   printf("%d\n",r); }

以下のようにした場合どうであろうか。

リスト2 void main() {   // 比較文字列[string]   char  a[]  = "string";   // 入力文字の格納用   char  b[100];   // 入力文字と比較文字列を比較するための変数   int       pos=0;   // 比較結果　true:入力文字は"string"と一致   bool  r  = true;   // 文字の入力   int result = scanf("%s",&b);     // 入力された文字列が"string"であるかを比較する   while( a[pos] != 0 && b[pos] != 0 ){     if( a[pos] != b[pos] ){       // 内容が異なっている場合は結果をfalseにする       r = false;       break;     } // if     pos++;   } // while   // 比較した結果を表示   printf("%d\n",r); } // main

随分と見やすくなったのではないだろうか。
リスト1はコメントを「How to」の視点で書いている
つまりどのようにするかをそのまま書いているだけて、ソースをみればすぐにわかってしまう。
リスト2はコメントを「why」の視点で書いている。
リスト2はコメントがソースで行おうとしている処理の意図を記述しているので、読むのが比較的容易であろう。
一方、リスト1は何をしているのかはわかるがその意図はくみ取りづらいので何をしているかを読み取るのに労力がかかってしまう。
Whyの視点でコメントを書くには「この処理はつまり何をしているのか」、あるいは「この処理が亡くなったらどうして困るのか？」ということを考えて書くとわかりやすく書くことができると思う。
このようなことを心がけるだけでソースの可読性はよくなる。