山下寛人オフィシャルブログ

オイシックス株式会社 執行役員 システム本部長 山下寛人の公式ブログです。

コメント

今日昼食のときにコメントを詳しく書くか書かないかの話になりました。

私は書かない派です。


人によっては1行1行コードと同じことを日本語のコメントで書く人もいますが

あれはさすがにナンセンスだと思います。


コードを直すたびにコメントも直さなくてはならず工数が2倍になります。


そこまで行かなくても、よく見かけるのが、コメントがあることにより

コードそのものがわかりにくくなるケースが結構あるということです。

例えばtempとか適当な変数名がつけられているけどコメントではこれは

○○ですなど説明が書かれている。

だったら変数名をそのとおりの名前にすればいいじゃないかということです。

クラス名やメソッド名も同様です。

コメントだと違うことが書かれている。

そのものずばりの名前にすればわかりやすいのに。


細かい処理は、要は何をしているのか補足したほうがいい場合があります。

例えばソケット通信など。

しかしそういう場合は、クラスやメソッド、関数などでまとめて、

要は何をしているのかを、その名前にすればよいです。


コメントなしでも読めるコードにしようと努力することにより

保守性の高いソースコードになるという考え方です。


とはいえコメントが必要になるケースはやはりあります。

パフォーマンスの都合でイレギュラーな書き方をしないといけない場合があります。

レアな例外パターンに対応するために一見予想できない処理を入れる場合もあります。

こういう場合、他の人が見て「なんでこんななってるの?」と思うので、コメントが

必要です。


またJavaの場合ですがJavaDocコメントのようにクラスやメソッドの使い方を

記述することは有効だと思います。

話はそれますがJavaDocコメントに中の処理をどうしているか書く人もいました。

中の処理でなく、クラスを使うほうから見てどう使うのかを書きましょう。


基本的に私はJavaを念頭に置いていますが、昔の言語のように変数名の長さ制限が

短かったり、複雑な処理や低レベルな処理をまとめて見えなくするのが難しかったり

する場合などは、コメントで補足する必要があると思います。

プログラム言語は、もともとコンピュータにしかわからない言語(マシン語)を、

人間でもわかるように記述できるようにしたものです。

そして、それはより人間がわかりやすくなるように進化してきました。

今日ではかなり人間が読めるように書けるようになったので、それに存分に

あやかるのがよいのではないでしょうか。