プログラムソースにコメントを書くか？

たまにはプログラミングネタでも。

先日ProDHCPのお問い合わせいただいたお客さんとのミーティングの際に、ProDHCPのソースライセンスの購入も検討しているというお話しになり、そのときに、「開発言語は何ですか？」「ソースのボリュームはどのくらいですか？」という感じにご質問をいただき、最後に「ソースにコメントはどのくらい書いてありますか？」との質問をいただきました。

私の返答は、

「ソースにコメントはほとんど書きません！」

です。お客さんは、ソースのボリュームに対してコメントのボリュームがどのくらいあるのかを知りたいという意味合いもあったようですが、ソースにコメントが必要かどうかという議論は、私が若い頃からずーっと盛り上がるテーマの1つです。

私の考えは、

• コメントを見ないと理解できないようなソースでは駄目。シンプルでわかりやすいソースこそ、バグが少なく性能も高い。
• コメントは度重なる仕様変更や改良の際にメンテナンスされないことが多い。信用できない内容ならない方がマシ。
• 不要なコメントがたくさんあると、ソースを眺める際に一度に画面に表示できる量が減り、把握しにくくなる。
• コメントがたくさんあると、ソースのインデントが崩れ、流れがつかみにくくなる。
• コメントに書かれた曖昧な文章より、ソースを見た方が理解できることは良くある。
• コメントはコンパイラがチェックしてくれないので、そもそも間違えていても気がつかない。
• 実際に動いているのは、ソースに書かれたものなので、ソースを読むのが一番正しい。

という感じに、まあ、屁理屈もあるものの、いくらでも出てきます。

コメント必要論を主張する方は、大抵他人が作ったソースを受け入れる立場の方が多いのですが、私の経験上、コメントが書いてあっても読んでくれるケースはほとんどなく、形式的に必要なだけ、ということが多かった気がします。詳細設計書と同じですね。どれだけコメントやドキュメントがあっても、結局はソースを読み書きできる人に相談が行くのです。

コメントが必要なケースももちろんあります。複雑なアルゴリズムの部分で、ここはこんな処理だよ、と概要を伝えてくれるコメントや、普段やらないような処理をあえて記述している場所に、ここはこういう理由でこうしている、という感じに注意を促すコメントは価値があります。しかし、請負の開発などで要求されるコメントは、関数1つにつき必ず１つヘッダをつけて説明を、とか、極端な場合、ソース1行に1つコメントを、とか、ソースの行数に対して何割のコメントを、とか、納品用の形式合わせにしか役立たない要求があることもあります。

/*
メイン関数
メイン処理を行う
*/
int main(int argc,char *argv[])
{

こんな感じのコメントが書いてあっても何の意味もないですよね。

私はこれまでプログラミング関連の著書を6冊書きましたが、サンプルソースにコメントはほとんど入れていません。コメントがないので分からないと言われたことは1回あったかどうかと言う感じでしょう。

プログラマーとして、ソースを他人に見せられるかどうかというのは一つの踏み絵みたいなものだと思っています。他人に見せられないようなごちゃごちゃしたソースは、多くのバグを含んでいたり、性能面で問題があることが多いものです。ハイテクニックを駆使して難解なソースを書くのも駄目です。仕事として作るソースは、メンテナンス性も大切なのです。シンプルなものが一番。極端な話、10年後に自分が作ったソースの問い合わせが来ても、すぐにソースを眺めて対応できるくらいでなければ駄目です。

プログラミングの仕事を依頼して、コメントの話題になったときに是非参考にしてみてください。また、若手のプログラマーの皆さんは、ベテランにどんどんソースを見てもらい、厳しい指摘をしてもらうと伸びますよ！