私はこんな時にコメントを書く

先日某所にて「コメントの書き方はどうあるべきか」という議論があったので「私はどのようにコメントを書くか」ということについて、書いてみたいと思います。あくまで持論なので「そうじゃないだろ！」ってとこもあるかと思いますが、そこはご容赦を :)

どんな時に書く/書かないのか

基本的に、コメントは必要な時に書きます。必要以上のコメントは可読性を下げるので避けています。「必要な時」とはその意図がソースコードから読み取れない時です。それ以外の場所には基本的には書きませんが、ソースコードの可読性を上げるため、処理の区切りやデータ構造の説明なんかは書くことがありますね。

どこでどのくらいの量のコメントを書くかは状況によりますが、出来るだけ詳しく書くように心がけています。オープンソースで公開されているものを中心に様々なソースコードを「どんな風に書いたら読みやすいかな」と思いながら参考にすることが多いです。個人的にはLinuxカーネルのソースコードなんかがオススメかな。

説明が必要なところに書く

ソースコードを見てると「なんでここで、こんなことしてるの？」って思う時がありますよね。そこを見つけたら、詳細に説明を書くようにしています。

情報は出来るだけ多く書くようにしています。これは他の人だけでなく、自分にも役立つからです。自分の書いたコードを半年後に見てみると分かります。あ、これは私だけかもしれませんが^^;

自分でソースコードを書いている時は書くべきことが分かってるので、こうした部分はなかなか見落としがちになります。なので、普段からソースコードを第三者の目で見る習慣をつけてます。しばらく時間を置いて自分の書いたコードを眺めてみる、なんてことをする時もあります。

処理を見れば自明なところには書かない

上記の逆で「ソースコードを見れば分かるところにはコメントは書かない」ようにしています。例えばこんなの。

    retry_count++;     /* increment retry counter */

見れば分かるソースコードかどうかは、シンプルなロジックかどうかもありますが、一番大切なのは名前だと思っています。クラス名/メソッド名/関数名/変数名など、ソースコードの名前が適切であれば、それ自体がドキュメントになりますよね。

とはいえ、英語ネイティブの人ではないので、ネーミングに迷うことはよくあります。そういう時は最初に思い浮かんだ名前を採用するようにしています。これは「いろいろ考えても、結局最初に考えた名前が一番よかったことが多かった」という経験則によるものです。

重複した情報は書かない

関数やメソッドの先頭にあるテンプレートってありますね。概要や入出力、戻り値の説明とかが書いてあるやつ。あれチームのコーディング規約で義務づけられていない限り、書きません。ああいうのは大抵最初だけ書かれて、その後メンテナンスされなくなっちゃうことが多いから。

なぜメンテナンスされなくなっちゃうかというと、関数やメソッドの定義と重複している情報が多いからかと。そもそも関数定義はそれ自体ドキュメントであり、概要も名前から自明なはずで、そこに書けない注意事項のようなものだけでいいのではないかと思います。

備忘録としての用法

「あとで直す」的なものもよく使います。皆さんもTODOとかFIXMEとかBUGBUGなんかは経験があるのでは！？

TODOを書くことは望ましくないと言う方もいますが、後で直そうと思って忘れてしまうことはよくあるので、私は好んで使ってます。大切なのは定期的に見直すことでしょうか。ずっと残っているのであれば、それはたぶん直さなくてもいいのです :)

そもそもなぜコメントを書くのか

というと「他の人（自分含む）にソースコードを理解してもらうため」というのが模範的な回答なんだろうけど、個人的には実行コードの一部なのだと思ってます。もちろんコメントなので動作に影響はないけれど、実行されるコードと同様、その人の考えが反映されているわけで、コメントも含めて「ソースコード」なんじゃないかと。

そんなわけで、コードに対して変更やバグ修正がされると同時にコメントも更新されるべきで、後から更新が面倒になるようなコメントなら、書かない方がいいのではないかと思ってます。書いてあることが一致してないと、たぶんその人のコードのコメントは読まれなくなってしまうんじゃないかなあ。

とはいえ

ここに書いたことは、実際には努力目標ぐらいの感じで、なかなか実践できていないことも多いです。コーディングルールや既存コードの暗黙のルールなどにより、思うように書けないことも多い。理想論かもしれないけど、でもだからこそ目指したいと思ってます。

皆さんはどんなルールでコメントを書いてますか！？