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

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

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

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

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

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

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

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

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

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

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

More

Categories

Tool 日々 Web Biz Net Apple MS ことば News Unix howto Food PHP Movie Edu Community Book Security Text TV Perl Ruby Music Pdoc 生き方 RDoc ViewCVS CVS Rsync Disk Mail FreeBSD Cygwin PDF Photo Zebedee Debian OSX Comic Cron Sysadmin Font Analog iCal Sunbird DNS Linux Wiki Emacs Thunderbird Sitecopy Terminal Drawing tDiary AppleScript Life Money Omni PukiWiki Xen XREA Zsh Screen CASL Firefox Fink zsh haXe Ecmascript PATH_INFO SQLite PEAR Lighttpd FastCGI Subversion au prototype.js jsUnit Apache Trac Template Java Rhino Mochikit Feed Bloglines CSS del.icio.us SBS qwikWeb gettext Ajax JSDoc Rails HTML CHM EPWING NDTP EB IE CLI ck ThinkPad Toy WSH RFC readline rlwrap ImageMagick epeg Frenzy sysprep Ubuntu MeCab DTP ERD DBMS eclipse Eclipse Awk RD Diigo XAMPP RubyGems PHPDoc iCab DOM YAML Camino Geekmonkey w3m Scheme Gauche Lisp JSAN Google VMware DSL SLAX Safari Markdown Textile IRC Jabber Fastladder MacPorts LLSpirit CPAN Mozilla Twitter OpenFL Rswatch ITS NTP GUI Pragger Yapra XML Mobile Git Study JSON VirtualBox Samba Pear Growl Mercurial Rack Capistrano Rake Win RSS Mechanize Sitemaps Android JavaScript Python RTM OOo iPod Yahoo Unicode Github iTunes God SBM friendfeed Friendfeed HokuUn Sinatra TDD Test Project Evernote iPad Geohash Location Map Search Simplenote Image WebKit RSpec Phone CSV WiMAX USB Chrome RubyKaigi RubyKaigi2011 Space CoffeeScript Nokogiri Hpricot Rubygems jQuery Node GTD CI UX Design VCS Kanazawa.rb Kindle Amazon Agile Vagrant Chef Windows Composer Dotenv PaaS Itamae SaaS Docker Swagger Grape WebAPI Microservices OmniAuth HTTP 分析基盤 CDN Terraform IaaS HCL Webpack Vue.js BigQuery Middleman CMS AWS PNG Laravel Selenium OAuth OpenAPI GitHub UML GCP TypeScript SQL Hanami Document SVG AsciiDoc Pandoc DocBook Develop Jekyll macOS Node.js Vite Heroku Transformer AI Data Cloud Wasm