ソフトウェア工学について その３ プログラムのドキュメント化を心がける

理想的なプログラムソースとは、究極的にはドキュメントとしても利用可能なものであると思う。
たとえば、以下のソースは何をしようとしているのであろうか。

1:if(a.x() != 0){ 2:　　b.cd(); 3:}

これでは、誰にもわからないであろう。
このような場合、コメントをつけることでわかりやすくすることが普通に行われるだろう。

1:// 利用者がいる場合は、全体に通知する。 2:if( a.x() != 0){ 3:  // 利用者がいる場合のシステム終了通知処理 4:  b.cd(); 5:}

上記のようにすることでだいぶ見やすくなったのではないだろうか。
さらに以下のようにしてみるとどうなるであろうか。

1:if( MySystem.NumberOfUser() != 0 ){ 2:  AllOfUser.NotifySystemTermination(); 3:}

上記ソースをみれば、コメントがなくてもシステムの利用者が0人でない場合は、すべてのユーザにシステムの終了を通知することが分かるのではないだろうか。
上記の場合、変数名やメソッド名を適切にすることによって処理の内容が自明になっていることが分かる。
日ごろからこのような心がけを行うことによってコメントは少なくとも非常に分かりやすいソースを記述することができると思う。