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

2009/10/04

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

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

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

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

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

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

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

Site Navigation
SNS Accounts (@aian)

普段はここら辺に住んでいます.