プログラムというのは、突き詰めれば実行されるために存在するものであり、読むためのものではありません。そもそもバイナリ形式になっていれば、読むことは容易ではないでしょう。しかしソースコードが手に入る場合もあります。自分自身の書いたプログラムなら当然ソースコードは手元にあるでしょう。商用ソフトウェアであってもその開発チームにいればソースコードを見ることができますし、オープンソースのソフトウェアならソースコードが公開されています。動的に実行されるインタープリタ型言語のプログラムの場合も、ソースコードの入手は容易です。ソースコードを読めば、そのプログラムがどういう意味を持っているのかは明確にわかるはずです。むしろ「プログラムの動作を完全に正確に知るには、結局はソースコードを見るしかない」とも言えるでしょう。要件定義書がたとえどれほど詳細に正確に書かれていたとしても、それが真実をすべて語ってくれるわけではありません。プログラムが実際にどう動くかが書かれているわけではなく、要件定義をした人間がどういう意図を持っているかが要約されているにすぎません。設計書もそうです。プログラムがどういう設計で作られる「予定だったか」が書かれているだけで、具体的にどう実装されたか、その詳細はわかりません。文書と実装との同期が切れている場合もありますし、書かれた文書がなくなってしまうこともあります。はじめから設計書が書かれないことだってあるでしょう。いずれにしろ、手がかりはソースコードだけ、ということです。

それを踏まえ、「では自分の書いているソースコードは果たしてどうだろうか」と自問してみてください。果たして、自分自身を含め、人に「このプログラムにはこういう意味があり、こういうことをしています」ということが明確に伝わるものになっているでしょうか。

「コメントに全部書いてあるから大丈夫」という人もいるかもしれません。しかし問題は「実行されるのはコメントではない」ことです。やはりコメントも他の種類の文書と同様に、誤ったことが書かれている恐れがあります。長い問、コメントを占くことは、無条件に「良いこと」とされてきたので、深く考えずに大量のコメントを書くプログラマもいます。何度も同じことが書かれていたり、コードを少し見ればすぐにわかるようなことが逐一説明されていたり。これではかえってコードがわかりにくくなってしまいます。

「このコードはコメントがなければわかりにくい」と感じたのなら、コメントを書くよりも、リファクタリングすることを検討した方がいいでしょう。コメントが大量にあると両面が見にくくなりますし、IDEの中には、コメントを自動的に非表示する機能を備えたものもあります。コードに何か変更を加えて、その変更の内容について説明したい場合にも、コメントに書くのではなく、バージョン管理システムへのチェックインの際に添えるメッセージに書くべきでしょう。

読んで、わかりやすいコードを書くにはどういうことをすればいいでしょうか。まず重要なのは、名前のつけ方です。システムを構成する各部分に、見てすぐに機能がわかるような名前をつけるのです。そのためには、コードの構成を「各部分の機能が非常に明確で、言葉で簡単に説明できる」ものにすべきです。コードをわかりやすくするには、部分同士ができるだけ依存関係を持たないようにすること、直交性(orthogonality)を高めることが大切です。自動テストを書いて「プログラムがどのような挙動をするはずか」を説明し、インタフェースのチェックをするというのも有効な方法です。その他、コードを少しでもシンプルにする方法がわかった時や、現状より少しでも良いソリューションが見つかった時には、即座にリファクタリングをすべきでしょう。可能な限り、プログラムを読みやすく、わかりやすくするのです。

コードを書くことは、詩やエッセイ、不特定多数の人に見せるブログ、あるいは大切な要件を伝えるメールなどを書くのと同じようなものと考えるべきです。表現を工夫し「このプログラムはどう動くものなのか」ということが、コードの読み手にストレートに伝わるようにするのです。書いた人間がそばにいて、逐一説明できるという状況ではなくても、書き手の意図が明確に伝わるようにするのです。プログラムのコードは、有用性を持つ限り使い続けられるので、思いがけず長く使われることがあります。コードが読んでわかりやすいものになっていれば、保守担当者はきっと書いた人に感謝するでしょう。逆に、他人が書いたコードを読んでいるのだけれど、何を言っているのかわからないという時は、ここに書いた方法を応用して、わかりやすく書き直すべきです。自分の目に触れるコードをすべてわかりやすいものにしておけば、あらゆる作業が円滑に進むようになります。