私が大学に入ったばかりの頃の話です。プログラミングの授業の1時間目、先生からBASICのコーディングシートが2枚配られ、黒板には「ボウリングのスコアを10個入力し、平均を求めるプログラムを書け」という指示が書かれました。それだけ書くと先生は教室を出て行ってしまいました。そんなに難しい課題ではありません。最終的にどんなコードを書いたかは忘れましたが、FOR/NEXTループを使って書いて、全部で15行あるかないかだったと思います。若い人は「コーディングシート」と言われてもわからないかもしれません。昔は、まずコードを紙に手で書いてからコンピュータに入力していたのです。1回に入力できる量は70行くらいに制限されていました。その時は、どうしてシートを2枚渡されたのかわからずに戸惑ったのを覚えています。よくわからないので、1枚目に下書きをして、2枚目に清書をすることにしました(私は字が恐ろしく汚いのです)。きれいにかけているということで少しは評価があがるかな、と期待もしていました。
次の授業のはじめに課題が返ってきたのですが、見て驚きました。合格点ぎりぎりの評価だったのです(後から思うと、それは私の大学生活を暗示していたのかもしれません)。そして、私がせっかくきれいに書いたコードの上には、こう走り書きしてありました。「コメントは入れないのですか?」
そのコードがどういうもので、どういう目的で書いたものなのかは、もちろん先生と私にはよくわかっていました。しかし、その2人だけがわかればいい、というものではなかったのです。その課題で私が学んだのは「コードは、次に見る人がすぐに理解できるように書く」ということでした。これは今後も決して忘れることはないでしょう。
コメントは悪ではありません。有効なものです。そして分岐やループなどと同様、プログラミングには必須の要素と言えます。ある程度以上新しいプログラミング言語には、一定の形式で書かれたコメントを基に自動的にAPIドキュメントを生成するツール(例：javadoc)などが用意されています。まずはじめにこういうツールを利用するのが良いでしょう。しかし、それだけではまだ十分とはいえません。プログラムのコードには「このコードはどういう目的で書かれたものか」のせつめいをするコメントを入れるべきなのです。「書くのに苦労したコードは、読むのにも苦労する」という格言がありますが、読むのに苦労するようなコードをコメントもつけずに放置すれば、顧客にも、自分の働く会社にも、同僚にも、そして将来の自分にも害を及ぼす事になります。
ただし、コメントは多く入れればいいというものではありません。コメントを入れるのは、あくまでコードをわかりやすくするためです。コメントを入れたことで帰ってコードがわかりにくくなっては意味が無いのです。必要にして十分な量のコメントを、適切な場所に入れること。「このコードで何がしたいのか」を読む人にわかってもらうこと、それが大事です。まずヘッダコメントには「プログラマがコード本体をまったく読まなくても利用することはできる」というくらいの情報を盛り込みます。そしてインラインコメントには、自分の次にコードを見て修正や拡張をする人の助けとなるような情報を適宜(てきぎ)盛り込みましょう。
随分前ですが、こんなことがありました。その時、私は上の人間に腹を立てていました。あるコードに関して彼らが採用を決めた設計がどうしても良いと思えなかったからです。若いプログラマにはありがちなことです。その設計を使用せよ、ということはメールで指示されたのですが、怒りのあまり、私はそのメールの文面をコードのヘッダコメントにコピー&ペーストしてしまいました。そして後になって、そのコードをコミット後にレビューするのは、まさにメールを送ってきた上司である、ということがわかったのです。そのとき初めて、CLM(Career-Limiting Move：出世の妨げとなるような行動)という言葉の意味が実感を伴って理解できたのでした。