プログラムのコメントやドキュメントは誰のためか

　作ったプログラムを使うのが本人のみなら、どんなプログラムでも問題ありません。他のひとに使ってもらうのでしたら、最低限のユーザインタフェースの基本ルールは抑えてないとダメです。さらに、プログラムそのものを他の人と共有したり一緒に開発したりするのなら、一定のコーディング規則に則ってないのはマナー違反です。ちゃんと書かれているプログラムを読めば、何をしたかったのかを理解することはできますが、プログラム本体を読まなくても、何がしたかったかすぐわかるようなコメントが書いてあると助かりますが。
　コメントとは、プログラミングする時に関数や変数、処理方法について説明する、プログラムの中に書き込まれた文章のことです。コンピュータはこれらのコメントを無視しますので、これはプログラマー本人や共同で開発するひと向けのメッセージです。プログラム言語によって、ここはコメントという決まった印があります。C系だと「//」や「/* */」、VBAだと「‘」、HTMLは「<!-- -->」、Pythonは「#」などです。
　プログラムの中に埋め込まれたコメントだけではなく、ちゃんとした開発現場では、プログラムをどうやって書いたかについてのドキュメントを作成することがあります。時には、プログラミングそのものを書く作業より時間がかかることもあり、常々無駄なことだなーと思っていました。プログラムがわかる人はプログラムそのものを読めば理解できますし、ドキュメントは単にちゃんと作っているかどうかを管理したい人のためだけに作られています。プログラムは日々変化しますから、その都度ドキュメントも変更するのは馬鹿げています。そこで、独自のルールでコメントと関数や変数定義を抜き出すソフトウェアを作って、ドキュメント作成をラクにしていたことがあります。
　世の中には同じことを考えている人がいるものです。doxygenというツールは、コメントに//のかわりに、//!などと書いた箇所を自動で抽出してくれて、WordやHTML形式の立派なドキュメントを出力してくれます。graphvizを付け加えると、クラスや関数の依存関係をグラフ化する機能もあって、とても立派な膨大なページのドキュメントが一瞬で作成されます。これを眺めていると、なんとなくすごい仕事をしたんだと実感（勘違い）できます。
　プログラムの中身はわからないけど、ちゃんと開発が進んでいるか確認したい、予算のエビデンスに使いたい、というような管理する人にはこのようなドキュメントを送りつけておけば良いでしょう。管理する人は、このようなドキュメントが送りつけられたからといって怒らないでください。あなたの管理方法を見直す必要があるのです。プログラムができない管理者は、ひそかにプログラマー達から軽蔑されていることが多いと思います。
　ただし、未来の自分のためにコメントを残しておくのはとても役立ちます。未来の自分でも、自分であることは変わらないので優しくしてあげましょう。