プログラムコメント - 桝原翔市の日記

先日、知り合いとプログラムのコメントについて以下のような議論になりました

僕「いまだに無意味にコメント書いたり、コメントアウトする人が多いですよね」
彼「え、コメントやコメントアウトってするべきじゃないんですか？」
僕「するべきじゃないでしょう。感覚的にそう思いますが、風潮としてもそうですし。
　　書籍でもそのように書いてるのが多いようです。」
僕「学校等で教わった人はコメントを”書くこと”が重要と教わってる人がいるようですが、
　　それは古いのではないでしょうか。」
彼「どうコメントを書くかは人それぞれなんじゃないですか？」
僕「確かにそうですが、それでもおおよそあるべき姿というのはあるのでは？」

といった感じで。
日々コードを読み書きするうえでの感覚としてはこうあるべきというのはなんとなくわかっていたのですが、実際細かくいうとどうすべきなのかということがあいまいだったので、軽くまとめてみることにします。

僕はオープンソースの有名なアプリケーションから、アマチュアの書いた野良コードにいたるまでいろいろなコードを読む機会が多いのですが、それらのコードを読むと

感覚として、僕はコメントは少ないほうが読みやすい
しかしコメントをやたら書くアマチュアが多い

という感じを良く受けていました。

あらためてググって見ると、「コメントをちゃんと書くようにと習ったけど、コメントは少なくしようね」との記事が結構見られます *1 *2 。これは書籍*3でも言及されていることで、コメントとは必要悪であって、本来は書くべきではない、とまで言われています。かといってコメント皆無のソースはほぼ読みにくいわけで、ではどのようにコメントを書くべきなのかということを以下にまとめます。

コメンテータになる前にコーダになれ

コメントをかっちり書いている、特にアマチュアのソースコードのほとんどが、コメントなしではそのロジックを読み取れないソースコードとなっている場合が多く見られます。これはそのコードの品質が非常に悪いことを表しており、この場合はコメントを一度消して、ソースだけで読み手が理解できるように書き直すべきです。

仕様書は仕様書、コメントはコメント

doxygenやjavadocを使ってソースからドキュメントを作成する場合のドキュメントコメントを書くならまだわかるのですが、そうでもない場合でも、コード内に仕様書を作ろうとしている人が散見されます。仕様書をソースの中に書いても誰も読みませんよ。

更新履歴や過去のコードをコメントに書かないでください

今日の開発環境ではバージョン管理システムがあるわけですから、日曜コーディングならどうでもいいですが、仕事ならマンパワーで頑張ってソースコード内で管理する努力をするよりバージョン管理システムを使ってください。コメントアウトされた過去のコードが蓄積しているソースほど読みにくい(シンタックスハイライトされててぎりぎり読めるレベル)物はないので、コメントアウトは一番避けるべきでしょう。よほど思い出のあるコードでなければ。

その他、ブログの記事にしてもその他情報源にしても、結局は書籍「Clean Code」の4章の内容とほぼ同じ内容がおおいようです。しかしこれらの記事を読んで思うのが「いまさら言われるようなことじゃないだろ」という感覚。コーディング・コードリーディングを続けていくとこれらの結論に自ずと達する人が多いと思うのですが、そうでもないのはなぜでしょうか？

上記の議論の続きで

彼「バージョン管理システムを使うこと前提ならまぁ」
彼「僕はコードをあまり書かないので良くわからないですが、
　　書籍やネット上の風潮が間違ってたらどうなんですか？」
彼「コメントは、そのコメントが書かれている関数のソースを
　　わざわざ読まないでいいようにするものだと認識してましたが。」

という発言にすべての答えが隠されているように思いました。彼はコードをあまり書かないそうですが、コードを書いてるけど読まない人も含めて以下のことが言えると思います。

開発環境を使いこなしていない

上でも記述していますが、よほど特別な場合がない限り、開発にはバージョン管理システムを導入すべきでしょう。それを使っていないということは使うべきものを使わずして作り出すものの質をわざわざ下げていることにほかなりません。

読み手の立場に立ったコメントを書いていない

確かにコーダの備忘録としてTODOなどを書いたりはしますが、所詮公開前の一時的なコメントでしかありません。システムがロールアウトした後にも残すコメントは書き手以外の人を含む不特定の人が保守する際に活用されるものです。もしコメントを”書くこと”が重要と教わり読み手の立場を考えないのなら、古いコードをコメントアウトしたり無駄なコメントを書いてしまうのもわからなくありません。

そもそもソースを読もうとしていない

上で書いている”彼”の誤解はソースを読むことがおそらく嫌いである、というあたりから来ているように思います。ソースを読むのが必要な状況は、ドキュメントなり何なりを読んでも見つからなかった情報を得るために読む、仕様を改変するために読む、ということが多いでしょう。たとえば PHP の使い方を知ろうとするためにいきなり PHP のソースを読む人はそういないでしょう。http://www.php.net/ へ行って関数のドキュメントを読むほうが数十倍速いです。しかしながら PHP の仕様を自分に合わせて変える必要があるなら、ソースを読み、書き換え、コンパイルする必要があります。そういった読み手の状況が、ソースを読まない人には把握できてないのではないでしょうか。

http://d.hatena.ne.jp/idesaku/20090703/1246593915 からの引用で