ドキュメント必要ですか？ | column

こんにちわ。ばたっちです。

仕様書、設計書、マニュアル。。。

ソフトウェア開発には、たくさんのドキュメントがありますね。

  「いつ書いてますか？」

「はぁ？」と思われるかもしれないので、もうちょっと詳しく。

  「先に書いてますか？後に書いてますか？」

あまり変わってないか。。A^^;

つまり、仕様書なら次の工程である設計の前、設計書なら次の工程のコーディングの前に作らせているか？というお話です。

XPはよく「ドキュメントを書かない」と言われます。なので、これ幸いと、ドキュメント書かなくていいと理解してしまう開発者もいるのですが、XPでは「必要なドキュメントを必要なとき」に書くのです。

「必要なドキュメント」は、あなたがマニュアル、仕様書が欲しいと言えば、納品物として書かせる必要があります。開発側は開発側で、内部で参照するための内部の設計資料を作るかもしれません。

では、「必要なとき」とはいつでしょう？

  「次の工程に必要だから、その前だろう」

と思うかもしれません。確かに開発側の内部の情報伝達のために、これらのドキュメントを作成することは役に立つかもしれません。 (ただし、XPでは通常、自動テストと動くコードにより、情報伝達するので、これらのドキュメントは不要であることが多いです(^^;)

設計の前の仕様書、コーディングの前の設計書、テストの前のテスト仕様書。。本当に必要でしょうか？もちろん、それぞれの情報は必要です。ここでは、Wordで書くような「きれいなドキュメント」が必要かということです。

※各工程毎の成果物として、作成させるお客さんもおられます A^^;

コーディングの前に設計書を作った。コーディング中に設計に変更があったので、コードを修正して、設計書も修正した。

コーディング期間の手直しくらいなら、このように整合を取ることもできるでしょう。でも、テスト期間中のバグ修正は。。

まぁ、普通はテストもして、デバッグして、修正して、いろんな報告とかして手一杯なので、ドキュメント修正は後回しにされます。A^^;

で、最後まで「後回し」にされて、コードとドキュメントの内容はずれたままになり、内容が一致していないので、ドキュメント読んでも分からず、「コードを見る方が早いね。」なんてことになります。

こうして「Write Only File」のできあがりです。(^^;

通常の開発にありがちなお話です。

では、XPならどうするか。。。

[仕様書の場合]

  内容は項目一覧を作成する程度に。
  どういう条件のときに、どのように振舞うかをはっきりと記述。
  (あいまいな記述の仕様書なんてゴミです)
  
  それを元に自動の受け入れテストを用意していく。
  (テストに振舞いが明確に記述されることに)
  
  納品が必要なら、最後に「きれいなドキュメント」を作成。

[設計書の場合]

  コーディング中は設計がどんどん進化するので、紙にUMLスケッチ
  する程度に。
  (ツールなんか使わなくても、手書きで十分。ホワイトボードを前
  に相談しながらメモして、印刷 or デジカメで写す(^^;)
  
  インターフェースの使い方、サンプルはテストコードに蓄積。
  (使用例が一番分かりやすいよね)
  
  最後にツール使って、きれいな UML図を作ってもよい。
  ドキュメントを自動生成する Javadoc、doxygen なども便利。
  
  納品が必要なら、コードが完成(設計が収束)した最後に「きれい
  なドキュメント」を作成。

[テスト仕様書の場合]

  テストしながらだし、テストコードにパターンがあるから不要(^^;
  
  納品が必要なら、テストコードから、テストパターンを抽出して
  Excelとかでまとめよう。

[マニュアルの場合]

  これはできあがってから。A^^;

必要なドキュメントを必要なときに作成作ることで、無駄を減らし、しいては、内容がイケてて、役に立つドキュメント、正しく動くコード、振舞いを保証するテストコードの全てがあなたのものに！

たかがドキュメント、されどドキュメント。せっかくなら、XPでいいドキュメントも手に入れませんか？(^_^)/~

フィードバック下さい！

やえもん: (Tue Aug 16 15:44:32 2005 )

> ※各工程毎の成果物として、作成させるお客さんもおられます A^^;
こればっかり :-(

つぅことで、営業に XP を理解させて客と交渉させるための How To もお願いします。

Chat (Lingr.com)

Informaiton

Daily

Column

Zope Solution

Extra

アーカイブ

OSS案内所

Site Info

関連リンク

フィードバック下さい！