Web アプリのドキュメントをもっと書きやすく

ドキュメントというと、Excel を方眼紙にした1関数1ページで仕様書を書くというふざけた習慣が一部にある。これは著しく生産性が悪いし、絶対に撲滅させるべき習慣だが、こうした、まだ「システムといえば大掛かりで当然」だった頃の古い体質に学ぶことが一つある。入力と出力を常に意識している点である。

なぜこうしたことを思ったかと言うと、ある Web アプリのある画面に関するコメントで、

• 入力（これは当然ブラウザからくる）
• 出力（画面用）
• 出力（他の画面に渡す用）

の3種類に変数が整理されて書かれていたものを見かけたから。

これは書くのは面倒だが実はありがたいコメントである。しかしドキュメント作成システムと相性が悪い。（ここでは PHPDoc を念頭に置いているが、）ドキュメント生成システムは原則的にクラスとメソッドに関するドキュメントを自動生成するものである。「画面」に対するドキュメントではない。これは PHPDoc のもとになった JavaDoc の性格を引き継いでいるのだろうが、Web アプリの場合は「画面1つ」に対して必ず何らかの「プログラムファイル1つ」が対応する。（もちろんモード分けによって画面数よりファイルが少なくなることはよくあるが。）ここが問題になるのだ。

何を言いたいかというと、GUI アプリと違って、Web アプリの場合は画面とドキュメントがうまくかみ合わないということである。GUI アプリはウィンドウやダイアログにクラスを割り当て、それらに対して操作を行うので、画面とドキュメントはスムーズに対応する。しかし Web アプリではそういうきれいな対応は作れない。

もちろん上の方法に倣ってすべての「画面」を「ページインスタンス」と見做し、全部オブジェクト指向で書くという方法もあるだろう。これならドキュメントシステムとの相性はよい。それが実現可能な言語ならそういう方法はアリだ。

でもそれは激しく書きにくいだろう。今度は HTML との相性が悪くなるし。

あ。でも画面を全部テンプレートに追い出して全部 OO で書くならイケそうだな。サーブレット + JSP な現場はどうなっているのかな？ 調査が必要かもしんない。

最近すっかりオブジェクト脳だ。