Entry

Doxygen や Javadoc を使っても仕様書が書けない人はどちみち書けない

2009年10月04日

Doxygen や Javadoc を使う理由に,「プログラマは仕様書を書くのが苦手」とかいった話があって,「それはお前の日本語能力の問題だろう。勝手に一般化して他人を巻き込むなよ。」とか思ってるんですけれど,そもそも仕様書を書けない人は,Javadoc のような道具を使ってもやっぱり書けないだろうな,と思ったりします。

たしかに,これらのプログラムは,ソースコード中にドキュメントを書くことができることから,メソッドやクラスを列挙するような項目については,一部自動化することができます。ソース修正と同じ機会にドキュメントもメンテナンスできることから,効率もよくなるはず。しかし,なんだか,ものすごい勘違いがあると思うんですけれど,Doxygen や Javadoc は,あくまでもドキュメントを書ける人の労力を低減したり,ドキュメントフォーマットを統一するためのものだったりします。仕様書を書けない人でも仕様書を書けるようにするためのものではない。そんな夢のようなプログラムがあるなら教えて欲しい。100万-200万出してもいいくらい(出すのは会社だが)。人件費の2人分や3人分軽く浮くと考えたら安いもんです。

一方で,Javadoc のような道具が出力するドキュメントは,中身がぜんぜんダメでも,それっぽく見栄えのする体裁で出力されてしまうことから,仕事をした気になってしまう。書けない人に使わせるのは,危険ですらあると思っています。

そういえば,そうした状況を踏まえてか,書店には Javadoc の書き方を丁寧に説明している書籍すらあります。

エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方
佐藤 竜一
翔泳社
売り上げランキング: 137946
おすすめ度の平均: 4.0
4 JavaDocの勉強が体系的にできる

本書は,文法だけでなく,ドキュメンテーションのお作法も含めて Javadoc を説明している点で,とても使い出があります。あたしゃ普段 C++ の人だけれども,手元に置いています。

「設計書はソースに書いてある」とか言っている人については,以前(熱く)書いたんですけれど(参照:qune: 詳細設計書はソースに書いてあるとか言っている人はよほど立派なソースを書くんだろうなと思った),どんな理由をつけたって書けないもんは何を使ったって書けないし,ダメなもんは何を使ったってダメだったりする。ひとりで開発する場合や,具体的に開発担当が限られていて,彼/彼女らが話し合うだけで解決するような小さな話なら,書面なんかない方が効率がいいんでしょうけどね。

効率云々はともかくとしても,仕様書が書けないのは,プログラマの属性のためでも,作業の性質のためでもない,ということは確かだったりします。ひとえに「あんたのドキュメンテーション・スキルの不足」がもたらしていることなんだぞ,と。

Trackback
Trackback URL:
Ads
About
Search This Site
Ads
Categories
Recent Entries
Log Archive
Syndicate This Site
Info.
クリエイティブ・コモンズ・ライセンス
Movable Type 3.36
Valid XHTML 1.1!
Valid CSS!
ブログタイムズ

© 2003-2012 AIAN