ソースコードは仕様書です

以前、ソースコードは仕様書であるという趣旨の記事を読んだことがあって、感銘を受けたことがあります。


オイシックスでは少ない人数で多くのものを開発していて、なおかつスピードが求められます。

そのような状況下ではドキュメントをきちんと整備するのはなかなか難しい。

また、生産性を最大化するために、ドキュメントは必要最低限にしておきたい。

必要最低限なラインはどこなのか常に考えていました。


今ではソースコードこそが最良のドキュメントであると考えています。

少なくともオイシックスのシステムにおいて。


ソースコードでないドキュメントは実際に動いているものと違っている場合がありますが、ソースコードは確実に今動いているシステムを表現しています。

トラブルが発生したとき、システム拡張をするとき、ドキュメントなしでソースだけでわかれば早いですよね。


ソースコードは詳細すぎるので概要を説明するドキュメントが必要、という考え方もあるかもしれません。

しかし今日のプログラム言語は細かい枝葉末節をまとめてクラスやメソッドという形でまとめることができます。

そうするとある処理がおおまかにどんなことをしているのか、ソースコード上で簡潔に表現することができるようになっています。


そもそも、プログラム言語は人間が理解しやすくなるように進化してきました。

ソースとは別のドキュメントはいらなくなる方向に進んでいるのです。


ただし、ソースコードがドキュメントであるためには条件があります。

それはソースコードの可読性が高いということです。

ある処理が1メソッドに詳細なレベルでベタっと書かれていたら理解するのに時間がかかるし、どう動いているのかはわかっても何がしたいのかわからない場合があります。

一連の処理が適度に分割され、クラス・メソッドに分けられていると、大まかに何をしているのかわかるようになります。

また、クラス名、メソッド名、変数名が的確であるということ。

Juchuu1Action、Juchuu2Actionなど、ろくに名前を考えていない場合、ソースだけでの理解が難しくなります。

それでもプログラムを書いた人に「Juchuu1ActionとJuchuu2Actionって何なの？」と質問すると、「Juchuu1Actionは○○でJuchuu2Actionは○○です」という回答が返ってきたりします。

だったらそういうクラス名にすればいいんです。

また変数名なんかもプログラムを書いているうちに意味が変わってきたりすることがよくあります。

それがそのままの変数名のままにされていると、プログラムを読む人が誤解をしてしまい、何回も読み直さないといけなくなります。

など。


そのためオイシックスでは可読性の高いソースコードを書くことを重要視しています。

以前コードレビューについて記載しましたが、コードレビューをしっかりやっているのはそのためです。


もちろん実際にはオイシックスでもそれなりにドキュメントは書いています。

でも、ドキュメントなしでわかるソースコードを書くことに注力しているということです。