Index: [Article Count Order] [Thread]

Date:  Fri, 19 May 2000 00:39:57 +0900
From:  Kentaro Fujinuma <fuji-k@....jp>
Subject:  [XP-jp:00368] XPractices	【 10. Documentaion 】
To:  extremeprogramming-jp@....jp (extremeprogramming-jp ML)
Message-Id:  <200005182107.IHC15609.VLJ-GK@....jp>
References:  <200005181951.JGE00755.JKGV@....jp>
Posted:  Thu, 18 May 2000 21:07:54 +0900
X-Mail-Count: 00368

藤沼@イイガです。

# 送信元アドレスを間違えてしまったために破棄されたようです。
 再送します。本来ならこちらが先のメールになります。

本当にすみません、送ったつもりになって忘れていました。m(__)m
いまさらですが、送ります。誤訳の指摘は大歓迎です。
それではよろしくお願いします。

あと、オリジナルは HTML なので即座に Web にあげることも可能ですが、
どうしましょうか。

---------------------------------------------------------------------
Documentation
ソフトウェアドキュメンテーション

ソフトウェアを記述する文書がいくつかあります。それは設計を文書化する
よりも要求を解釈するためであることがより一般的です。私たちは時折いく
つかの特に困難な領域へのアプローチを文書化します。私たちはコードを文
書化することは「決してしません」(稀にコメントするだけです)。

これは私たちがなぜさらなる文書化をしない かを示すいくつかのよい理由です:

・私たちはそれがさらに早く前進することを助けるとは信じていないので 
・私たちはそれがシステムをより信頼できるものにするとは信じていないので 
・私たちはそれがシステムをより維持しやすくすると信じていないので 

これは私たちがなぜもっと文書を作成するべき かを示すいくつかのよい理由です:

・私たちのプロセスから他のグループが恩恵を得る助けになるかもしれないので 
・私たちの顧客が読みたいという興味を起こすかもしれないので 
・雑誌記事や会議での有益な文書の基礎を提供するかもしれないので 

あなたが考慮に値するかもしれないエリアの一つに、私たちの行っているCRC 
カードの使用があります。私たちは普通はカードの上に何も書きませんし、
もし書くならば私たちはクラス名を書くでしょう。私たちはそれを移動させ、
戻したり取り出したりして、それによって私たちが設計しているプロセスを
実際に表現します。そして、私たちはカードを投げ捨て、コードを書きます!

あなたは、カードを投げ捨てたのに、どうやって私たちが設計がどうなって
いるかを後から知るのかを尋ねるでしょう。私たちの回答は、設計はコード
の中に表現されているというものです。もし私たちが文書を持っているので
あれば、それは時代遅れか更新のために時間を費やさなければならないで
しょう。私たちはコードを可読性のあるものにし、クラスが何をするかを記
述するためにおそらくクラスコメントを用いるでしょう。そして私たちの高
いレベルのコミュニケーション、そしてまた私たちはコードの所有を実践し
ないという事実が、全体のシステム設計について私たちが何をする必要があ
るかを私たちは全て知るように確保します。

私たちはプロセスの初期に、システムの各部分のための文書による (literate) 
計画をいくつか書いています。世界中のほとんどのシステムの文書のように、
これらは最新にはされていません。開発者はそのプロセスを楽しみませんし、
それを継続するのに十分な有益さを見出しません。

私たちはもっとするべきでしょうか?。それは分かりません。私たちは将来
のある時点で苦しむのでしょうか?。それは分かりません。私たちは、私た
ちのプロセスを変更する必要があるというサインを出して警告しつづけます
し、もし私たちがより多くの文書を作成する必要があるというサインを見た
ら、私たちはそうするでしょう。

---
オリジナル http://www.xprogramming.com/
Copyright (c) 1999, REJeffries et al. (ronjeffries@....org)

-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 Kentaro Fujinuma / IIGA Co., Ltd. / Network Administrator
 Contact: E-mail: fuji@....jp 
          Tel: 03-5296-0389 / Fax: 03-5296-0386
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

------- End of Forwarded Message

-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 Kentaro Fujinuma / IIGA Co., Ltd. / Network Administrator
 Contact: E-mail: fuji@....jp 
          Tel: 03-5296-0389 / Fax: 03-5296-0386
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-