OPC Diary

« GUIでグイグイリンク(Linq)を書こう | メイン | MSDN ライブラリ移行のお知らせ »

2008年04月20日

設計時ドキュメント書く？ - もちろん書く！

設計時ドキュメント書く？ - 新日々此何有哉

なんていうか、出身が汎用計算機のプログラマじゃなくて、分散制御システムのアプリケーションエンジニア出身としては、純粋な計算機のプログラマに皆さんがおっしゃる、ソースがあれば設計書いらないっていうのは、さっぱり理解ができません。

その青写真(設計)もないのにあなたどうやってビル建てるわけと思うわけです。

まぁ最近では施主の方と相談しながら一部屋ずつ増やしていく方法もあるようですが、その方法では100階建て無理ぽとも思ったりするわけです。

まぁソフトウェアの話なので、慣例に従い建設に例えてみました。

なんかこの話の発端は、比嘉さんの以下のBlogらしいのですが、勘違いしちゃいけないのは、この記事、ドキュメント書くなって話じゃなくて、コードも読み書きできないような、わけわからん奴に仕様書や設計所書かせるなって話を比嘉さんはしているのであって、それはあたりまえの話です。

浜口さんに贈るSI業界を良くする方法 - ひがやすを blog

建築士レベルの構造学やその他の知識や技量も持たない人に、あなたは自分や家族が住む家を建ててほしいですか、設計してほしいですかと言っているだけのことです。

また10年後子供が増えて建て増しするときに、設計図/書なしにどうやって改築するんでしょう。いきなり壁ぶち壊してみますか？家ごと崩れたりして。。まぁ家ごと崩れちゃうのはITではよく見る光景ですが。

ということで、設計書は何らかの形で必要です。家の改築で、もともとの家を壊したり住めなくなるようにしない程度には必要です。

さて、では何を描くかだけど、基本的に以下のことが分かればいいと思うよ。

1. モジュールの分解(どんなクラスがあんねん)
2. モジュールの外観(インターフェイス仕様だね)
3. モジュール間のインタラクション(インターフェイスの呼び出しには必ず順序性がある)
4. モジュールが使用するデータの構造（ER図でもクラス図でもお好きなのでどうぞ)
5. 設計趣意(何でこう作ったのか)
6. まぁ自分で通信プロトコルを作ってしまった場合にはその仕様

このうち1と2に関しては最近ではIDEが結構面倒見てくれるね。1に関してはVisual Studioであればクラスデザイナで充分。2に関してはC#のXML DocumentやJava DOCで充分だと思う。

3．は自動ドキュメント作成ツールが絶対作ってくれない文書なんだけど、3ヶ月後後改築(改造や修正)を行う場合には絶対に必要だ。クラス図やインターフェイス説明をにらめっこしたところで、それをどう使うのかはすぐにわからないし、場合によってはさっぱりわからない。だからモジュールのインターフェイスはどういう時にどの順番で使うのか文書にしておく必要がある。（UMLシーケンス図とか）ちなみMSDNライブラリにもこれがなくて、添付サンプルがちゃっちーと困るよね。

4．はいいよね。これなしにそこに転がっている知らない拡張子のバイナリファイルをどう処理しろというの。

5．これが一番大事。なんでそのインターフェイスなのか、なぜそのモジュール間のインタラクションシーケンスはそうなっているかなんて、やっぱ後からだとさっぱりわからない。なのでなぜこう作ったのかは絶対に書いておくべき。ある意味どう使うかより重要。また、いきなりコードやUMLのクラス図をかき出す前に、なぜそう作るつもりなのかを文書に書こうとすると、これが考えに足りていなかったといった意外な発見もある。

6．作ったら責任を持って書くこと。後の人にコードを追わせるどころか、パケットキャプチャさせるといった愚行を行わせないようにすること。結局そうなるんだけどさ、せめて自分の作ったものぐらい。。

投稿者 ishisaka : 2008年04月20日 20:54