6.17.2013

コメントについて

既存のコードで、コメントが多くていかにも複雑なのを読むとき、ふと思いついてコメントを全部削除、詰めてインデント整えてみると意外と読めるようになった経験がある。

ソースコードのコメントは必要なところにだけあると役に立つ。
一行ずつコメントがあるのは論外だけど、ちょっと読めば分かるようなところにコメントが書かれているのもダメだよね。
実感として、単にコメントが多いってだけで読むのがうんざりするコードになるし、逆にコメントが無くて複雑で何をやってるのか分かんないコードも読むのがうんざりする。
「コメントを読めば読解に役に立つって部分にしかコメントを付けちゃいけない」んだと思う(この感覚が難しんだけど)。
ついでに言うとプログラムの仕様についてコードの中にコメントで書くのもダメだと思う。コードの読解には関係ないし、それは他のテキストか、メソッドの説明に書くべきだよね。

書いていいコメントは、フィールドの説明とかメソッドの説明(JavaDocになるやつ)と、すっごい変なコードで何をやったのか分かんないだろうなと思う部分だけ。例えば「このループは文字列の”¥”を取り除きたいだけです」とか書くと、その珍妙なループは読み飛ばしてokだ、と分かるようになるし(あるいはリファクタリングされる)、「配列x、y、zはフーリエ変換して部分標準偏差から平均熱量分布を…」とか書くとその部分は読み飛ばされるか、そのソースコードは閉じられて二度と開かれないかな。
何が言いたいかというと、変なコードを書かない限り、コメントは不要だということ。

もしもコードを書いてて、コメントを書こう、と思ったなら、今書いたコードか、これから書くコメントか、どちらかが変なんだよ。
コードが変だ(あるいは数学的で難しい)、と分かってる時だけ(そして様々な理由でそのコードを改善することが出来ないときだけ)コメントを書こう。

0 件のコメント:

コメントを投稿