Key
phrase |
キーフレーズ |
>Top
0. Introduction:
- I could encounter this thesis from the reference of description
of Waterfall method in Wikipedia. The authors, David L. Parnas
belongs to Computer Science Dept, Univ. of Victoria BC, Canada
and Paul C. Clements, computer Science and Systems Branch, Naval
Research Laboratory, Washington DC, USA.
- As the software industry plays very important function in every
fields today, such objective and persuasive explanation about development
methodology and importance of documentation is invaluable.
|
0.
序:
- 本論文はWater fall手法に関するWikipediaの解説の中の参考文献として出会うことができた。
- ソフトウェア産業があらゆる場所で重要な役割を果たしている現状では、その開発方法を巡るこのような客観的で説得力のある説明は貴重である。
- 本論文は左記URLからダウンロードし、引用した。
|
- This thesis is downloaded and quoted from the following URL as
of May 1, 2007.
http://users.ece.utexas.edu/~perry/education/360F/fakeit.pdf
|
>Top
1. The search for the philosopher's
stone: Why do we want to rational design process?
- A perfectly rational person is one who always has a good reason
for what he does. Each step taken can be shown to be the best way
to get to a well defined goal. Most of us like to think of ourselves
as rational professionals.
- However, to many observers, the usual
process of designing software appears quite irrational. Programmers
start without a clear statement of desired behavior and implementation
constraints. They make a long sequence of design decisions with
no clear statement of why they do things the way they do. Their
rationale is rarely explained. Many of us are not satisfied with
such a design process.
- That is why there is research in software
design, programming methods, structured programming and related
topics.
- Ideally, we would like to derive our programs from a statement
of requirements in the same sense that theorems are derived from
axioms in a published proof. All of the methodologies that can
be considered "top down" are the result of our desire
to have a rational, systematic way of designing software.
- This
paper brings a message with both bad news and good news. The bad
news is that, in our opinion, we will never find the philosopher's
stone. We will never find a process that allows us to design software
in a perfectly rational way. The good news is that we can fake
it. We can present our system to others as if we had been rational
designers and it pays to pretend do so during development and maintenance.
|
1.
賢者の石探し：なぜ我々は合理的な設計プロセスを必要とするのか？
- 完全に合理的な人とは、常に自分がすることについてしかるべき理由がある人である。その歩む一歩は、明確なゴールに到達する最善の道であることを示す。我々のほとんども自分のことを合理的なプロフェッショナルと思い込んでいる。
- しかし、第三者にとっては、いつも行われるソフトウェアの設計プロセスは不合理なものに見える。プログラマは望ましいやり方や作成の制約についての何らの明示することなく開始する。彼らはなぜそのようにしてするかについての明確な説明もなく、長い一連の設計方針を決めてしまう。彼らの理論的な説明はなされることはほとんどない。多くの人達はこのような設計プロセスには満足もしていない。
- ここでは、その理由を明らかにすべく、ソフトウェア設計、プログラミングの方法、構造的プログラミングなどについて研究してみる。
- 理想的には、我々のプログラムはあたかも公表された公理から導いた定理を導くようなやり方で、要件定義からプログラムを生成したいと思っている。トップダウン方式という方法論はすべて、合理的かつシステマティックにソフトウェア設計が作成され得るものと見なしている。
- この小論は善悪両面のメッセージを含んでいる。悪い意味としては、我々の意見では、我々には決して（錬金術師の求めた）賢者の石は存在しない。我々は決してソフトウェア設計においては完全に合理的な方法は見つけることはできないということである。良い意味としては、我々はそのように見せかけることはできる。我々が構築したシステムは他人にとっては、あたかも開発や保守の期間は合理的な設計者と見なすことが割に合うと言えることである。
|
>Top 2. Why
will a software design "process" always be an idealization?:
|
2.
ソフトウェア設計プロセスはなぜ常に理想化されるのか:
- ソフトウェアのプロジェクトが合理的な方法で進められることは決してない。その主な理由は以下である。
- (1) 多くの場合、ソフトウェアシステム構築を依頼する人は、自分の要求項目を正確に知らないし、我々に知っていることをすべてを語ることもできない。
- (2) もし開始前にすべての要求項目を知ったとしても、ソフトウェア設計に当たって他に知らなければならないことはまだ沢山ある。それらの詳細は、作成の途中段階で我々に知らされることになるのである。その結果、我々の設計は無駄になり、手戻りが生じざるを得なくなる。我々としては無駄な作業な最小となるように努力はするが、できた設計は合理的な設計プロセスとは言えないものになってしまう。
- (3) たとえすべての関連する事実を開始前に知り得たとしても、経験によれば、人間である以上、設計を行い正しいシステムを構築するために考慮しないければならない詳細をすべて完全に充足させることは不可能である。ソフトウェア設計プロセスとは、我々が管理可能な情報であるものに限って考慮して実施されるものである。しかし、我々は考慮すべき事項を分離する以前に、我々はエラーをしてしまうこともあり得る。
- (4) たとえ我々がすべての必要な詳細を考慮したとしても、非常に簡単な案件の場合を除いて、すべて外部の理由によって変更を余儀なくされる。これらの変更によってはそれまでの設計で決めたことが無駄になる。そうして仕上がる設計は合理的な設計プロセスで作成されたものでなくなっている。
- (5) 人間によるエラーは、人間を使わなければ避けることは可能である。考慮事項を分離した後でもエラーは起こりえるのである。
- (6) 我々は、しばしば先入観をもった設計アイデア、我々がすでに開発したアイデア、関連案件から得られたもの、あるいはどこかで教わったものに囚われてしまうことがよくある。時には我々は試行として、好ましいアイデアを活用するためにプロジェクトを始めることがある。これらのアイデアは合理的なプロセスによる要求項目からは生じてこない。
- (7) 我々はしばしば、経済的な理由から、他案件で開発したソフトウェアを活用したくなることがある。また他の場合では、他の進行中の案件をソフトウェアを教養したくなることもある。その結果、ソフトウェアはいずれの案件にとっても理想的なソフトウェアとはならないかも知れない。つまり要求項目にのみ基づき開発されたソフトウェア言えないかもしれないが、十分出来映えもよく努力に見合うものではあるが。
- これらの理由によって、ソフトウェア設計者の描くデザインは合理的で、エラーフリーで、要求項目から導き出されたものであるといういのは現実あり得ないことになる。ソフトそのようなやり方で開発することも今までもなかったし、これからもないであろう。教科書に書いてある小さなプログラムであったも、現実のものとは言えない。そのプログラムは著者が意図するまで推敲されたもので、実際にはそのようなことはあり得ない。
|
>Top 3. Why is a description
of a rational idealised process useful nonetheless?:
- What is said above is quite obvious, known to every careful
thinker, and admitted by the honest ones. In spite of that we
see conferences whose theme is the software design process, working
groups on software design methods, and a lucrative market for
courses purporting to describe logical ways to design software.
What are these people trying to achieve? If we have identified
an ideal process but cannot follow it completely, we can still
follow it as closely as possible and we can write the documentation
that we would have produced if we had followed the ideal process.
This is what we mean by "faking a rational design process".
Below are some of the reasons for such a pretense:
- (1) Designers
need guidance. When we undertake a large project we can easily
be overwhelmed by the enormity of the task. We will be unsure
about what to do first. A good understanding of the ideal process
will help us to know how to proceed.
- (2) We will come closer to a rational design, if we try to
follow the process rather than proceed on an ad hoc basis.
For example, even if we cannot know all of the facts necessary
to design an ideal system, the effort to find those facts before
we start to code will help us to design better and backtrack
less.
- (3) When an organisation undertakes many software projects
there are advantages to having a standard procedure. It makes
it easier to have good design reviews, to transfer people,
ideas, and software from one project to another. If we are
going to specify a standard process, it seems reasonable that
it should be a rational one.
- (4) If we have agreed on an ideal process, it becomes much
easier to measure the progress that a project is making. We
can compare the project's achievements with those that the
ideal process calls for. We can identify areas in which we
are behind (or ahead).
- (5) Regular review of the project's progress
by outsiders is essential to good management. If the project
is attempting to follow a standard process, it will be easier
to review.
|
3.
それでもなお合理的な理想プロセスによる記述が有効である理由：
- 上記で述べたことは全く明らかなことであって、注意深く考えれば、あるいは正直に認めれば、誰でも知っていることである。にもかかわらずソフト設計プロセスをテーマとする会議では、フトウェア設計方法の分科会や実践的なソフトウェアの論理的設計を説明コースが語られる。そこでは何が目的なのだろうか？もし理想的なプロセスが見つかってもそれを完全に利用できないのであれば、我々はできる限りそれに近づき、理想的なプロセスに従ってソフトウェアを開発したとしてドキュメントを書くことができる。これこそ合理的な設計プロセスができると見なすということである。以下この見せかけのいくつかの理由を述べる。
- (1) 設計者にはガイダンスが必要である。我々が大規模プロジェクトを請け負う時、まずその作業の膨大さに圧倒されてしまう。何から手をつけていいのか不安に駆られる。理想的のプロセスに対する理解があれば進め方を手助けになる。
- (2) 我々は、アドホックな進め方ではなく、合理的なプロセスに準拠すれべ、合理的設計に近づくようになるだろう。例えば、理想的なシステム設計に必要なすべての事実を知らなくても、コーディングの前にそれらの事実を見つける努力はより良くまた手戻りの少ない設計を行う助けになる。
- (3) 組織として多くのソフトウェア勝発案件に関わることで、標準的な進め方を持つ有利性がでてくる。それは案件の間での良い設計レビュー、開発要員、アイデア、ソフトウェア得やすくなるのである。もしある標準プロセスを特定して、それが合理的なものであろうということになるのは当然である。
- (4) 我々が理想的なプロセスであると合意したとすれば、それはプロジェクトの進捗状況を測る上で参考になる。その理想的なプロセスが要求するものと対照の案件の達成とを比較することができる。また遅れている（あるいは進んでいる）領域を示すこともできるのである。
- (5) 案件の進捗を外部によって定期的にレビューすることが良い管理方法と言える。もし案件は標準的なプロセスに準拠していれば、レビューすることもずっと容易になる。
|
>Top 4. What should
the description of the development process tell us?:
- The most useful form of a process description will be in terms
of work products. For each stage of the process, this paper describes:
- (1) What product we should work on next?
- (2) What criteria must that work product satisfy?
- (3) What kind of persons should do the work?
- (4) What information they should use in their work?
Management of any process that is not described in terms of work
products can only be done by mind-readers. Only if we know which
work products are due and what criteria they must satisfy can we
review the project and measure progress.
|
4. 開発プロセスの記述は何を意味するのか ？:
- 最も役立つプロセスの喜寿何時とは作業の成果物の中にある。プロセスの各ステージに関して言うと、
- (1) 次に取りかかる成果物とは何か？
- (2) その成果物が満足いくものである基準とは何か？
- (3) そのようなタイプの人がその作業に関わるべきか？
- (4) その作業に活用すべき情報とは何か？
- いかなるプロセスの管理も成果物の用語では記述されず、ただ心を読むことによって可能となる。我々は、どの成果物がいつまでに完成させ、どの基準を満たせば、我々は案件をレビューし、進捗を測ることができるのかを知ることができるに過ぎない。
|
>Top 5.What is the rational
design process?:
- This section describes the rational, ideal software design process
that we should try to follow. Each step is accompanied by a detailed
description of the work product associated with that step. The
description of the process that follows includes neither testing
nor review. This is not to suggest that one should ignore either
of those. When the authors apply the process described in this
paper, we include extensive and systematic reviews of each work
product as well as testing of the executable code that is produced.
- A. Establish and document requirements.
If we are to be rational designers, we must begin knowing what
we must do to succeed. That information should be recorded
in a work product known as a requirements document. Completion
of this document before we start would allow us to design with
all the requirements in front of us.
|
5.
合理的な設計プロセスとは何か？:
- ここでは我々が従うべき合理的かつ理想的なソフトウェア設計プロセスは何かを述べる。各ステップは成果物のそのステップに関連んした詳細な記述に従っている。プロセスの記述にはテストやレビューは含まれない。これらを無視すべきという訳ではないが。本論文記載のプロセスを適用する倍医は、各成果物についてのシステマティックなレビューを含め、また生成したコードについてのテストも含めるものとする。
- A. 要求項目を規定し文書化すること。
もし我々が合理的な設計者であるならば、まず成功するために何をなすべきか知ることから始めなければならない。その情報は要件定義書に記録される。その文書が作業開始前に完了することで我々はすべての要求項目を前提に設計が可能となる。
|
- >Top 1. Why do we need a requirements
document?
- (1) We need a place to record the desired behaviour of
the system as described to us by the user; we need a document
that the user, or his representative, can review.
- (2) We want to avoid making requirements decisions accidentally
while designing the program. Programmers working on a system
are very often not familiar with the application. Having a complete
reference on externally-visible behaviour relieves them of any
need to decide what is best for the user.
- (3) We want to avoid duplication and inconsistency. Without a
requirements document, many of the questions it answered would
be asked repeatedly throughout the development by designers,
programmers and reviewers. This would be expensive and would
often result in inconsistent answers.
- (4) A complete requirements document is necessary (but not sufficient)
for making good estimates of the amount of work and other resources
that it will take to build the system.
- (5) A requirements document is valuable insurance against the
costs of personnel turnover. The knowledge that we gain about
the requirements will not be lost when someone leaves the project.
- (6) A requirements document provides a good basis for test plan
development. Without it, we do not know what to test for.
- (7) A requirements document can be used, long after the system
is in use, to define the constraints for future changes.
- (8) A requirements document can be used to settle arguments
among programmers; once we have a complete and accurate requirements
document, we no longer need to be, or consult, requirements
experts. Determining the detailed requirements may well be
the most difficult part of the software design process because
there are usually no well-organised sources of information.
|
- 1.なぜ要件定義書が必要なのか？
- (1) 我々としては、ユーザによって我々に対して記述されたシステムの理想的な振る舞いについて記録する場所が必要である。それはユーザあるいはその代表がレビューするのにも必要な文書でもある。
- (2) 我々は、プログラムを設計している途中でたまたま要件定義を回避したくなる。システムを作成しているプログラマはしばしばアプリケーションには不慣れである。外側からの振る舞いに関する完全な参考書があればユーザにとって何が最良かを決める必要がでてきた時の救いになる。
- (3) 我々は重複したり、矛盾を生じたりするのを避けたい。要件定義書がなければ、設計者、プログラマ、レビューワによって開発の期間中繰り返し多くの質問が飛び交うことになる。このことが引いては矛盾を含む回答を呼び起こすことになる。
- (4) 完全な要件定義書は、作業量を的確に見積、当該システムを構築するのに他資源を調達する上で (それだけで十分ではないものの)必要である。
- (5) 要件定義書は要員当たり売上コストに対する貴重な保険でもある。それは誰かが案件を去るとしても、要件に関して得られた知識が失われないで済むからである。
- (6) 要件定義書はテスト計画を展開する上での基礎となる。それなしには、何をテストしてよいのかわからなくなる。
- (7) 要件定義書はシステム活用後も、将来の変更の際の制約条件を定義する上で、ずっと長く利用される。
- (8) 要件定義書はプログラマ間の論争を解決するためにも利用され得る。一度完全で正確な要件定義書ができると、我々はもやは要件定義の専門家やコンサルが必要でなくなる。
詳細な要件綱目を決めることはソフトウェア設計プロセスの最も難しいことである。それはうまく組織化された情報源が通常は存在しないからである。
|
- 2. >Top What goes into the requirements document?
The definition of the ideal requirements document
is simple: It should contain everything you need to know to write
software that is acceptable to the customer, and no more. Of
course, we may use references to existing information, if that
information is accurate and well organised. Acceptance criteria
for an ideal requirements document include:
- (1) Every statement
should be valid for all acceptable products; none should depend
on implementation decisions.
- (2) The document should be complete in the sense that if a product
satisfies every statement, it should be acceptable.
- (3) Where information is not available before development must
begin, the areas of incompleteness should be explicitly indicated.
- (4) The product should be organised as a reference document
rather than an introductory narrative about the system. Although
it takes considerable effort to produce such a document, and
a reference work is more difficult to browse than an introduction,
it saves labour in the long run. The information that is obtained
in this stage is recorded in a form that allows easy reference
throughout the project.
|
- 2. 要件定義書の何を調べるのか？
理想的な要件定義書を決めるのは簡単である。それは顧客がアクセスするソフトウェアを記述するために必要なすべてのことを包含しているかどうかであり、それ以上でもない。もちろん、既存の情報が正確であってうまく組織化されていれば参考にすることができる。
正確な要件定義書の基準とは以下のことを包含するものである。
- (1) すべての記述はすべての成果物にとって有効であること。ソフトウェア制作の際の決定に依存しないことである。
- (2) 成果物が各記述を満足することで受入可能となり、そのことが即ち、その要件定義書が完全である意味とする。
- (3) 開発前に情報が入手できない箇所については、不完全である箇所を明示しておかなければならない。
- (4) 成果物は、システムに関する導入的な解説ではなくむしろ参考文書として組織的に記述されなければならない。このよな文書を作成するおうに相当の努力を払うとしても、当初の導入文書としてよりも参考文書として利用できる方が難しいが、長期的には労力が省ける。この段階で得られる情報はプロジェクト期間中いつでも参考となるような形式で記録される。
|
- 3. >Top Who writes the requirements document?
- Ideally, the requirements
document would be written by the users or their representatives.
In fact, users are rarely equipped to write such a document.
Instead, the software developers must produce a draft document
and get it reviewed and, eventually, approved by the user representatives.
- 4. What
is the mathematical model behind the requirements specification?
- To assure a consistent and complete document, there must
be a simple mathematical model behind the organisation. The
model described here is motivated by work on real-time systems
but, because of that, it is completely general. All systems
can be described as real-time systems, even if the real-time
requirements are weak.
- The model assumes that the ideal product
is not a pure digital computer, but a hybrid computer consisting
of a digital computer that controls an analog computer. The
analog computer transforms continuous values measured by the
inputs into continuous outputs. The digital computer brings
about discrete changes in the function computed by the analog
computer. A purely digital or purely analog computer is a special
case of this general model. The system that will be built is
a digital approximation to this hybrid system.
- As in other
areas of engineering, we can write our specification by first
describing this "ideal" system
and then specifying the allowable tolerances.
- The requirements
document treats outputs as more important than inputs. If
the value of the outputs is correct, nobody will mind if the
inputs are not even read. Thus, the key step is identifying
all of the outputs.
- The heart of the requirements document
is a set of mathematical functions described in tabular form.
Each table specifies the value of a single output as a function
of external state variables.
|
- 3. 誰が要件定義書を書くのか？
- 理想的には、要件定義書はユーザまたはその代表によって書かれる。実際には、この文書を書ける程装備されている場合はむしろ稀である。その代わりにソフトウェア開発者がその原稿を記述し、ユーザによってレビュー、承認してもらうのである。
- 4. 要件定義書の背後にある数学的モデルとは何か？
- 一貫性のある完全な文書を作成するためには、組織の背後に簡潔な数学モデルが必要である。ここで記載するモデルはリアルタイムシステムの場合であり、それ故、ごく一般的なものである。すべてのシステムは、たとえリアルタイムの要求が希薄であるとしても、リアルタイムシステムとして記載される。
- そのモデルは、理想的な成果物は純粋にデジタルコンピュータではなく、アナログコンピュータをコントロールするデジタルコンピュータというハイブリッドコンピュータであるということである。アナログコンピュータは連続した値を入力して連続した値を出力する。デジタルコンピュータはアナログコンピュータで計算した関数に飛び飛びの値を入れて処理する。純粋なデジタルコンピュータも純粋なアナログコンピュータもこの一般モデルでは特別な場合となる。システムはこのハイブリッドなシステムをデジタル側から近似して構築することになる。
- エンジニアリングの他の分野では、まず理想的なシステムを想定して仕様を描き、それから何処まで許容されるかと特定していく。
- 要件定義書では、出力の方が入力よりもずっと重要である。もし出力の値が正しければ、入力がどう読み取られているのかは誰も気にしない。このようにすべての出力を決めることが鍵となるのである。
- 要件定義書の真髄は、表形式で示される一連の数学的な関係式である。各々の表は、外部の変数が、一定の値として出力されることを規定している。
|
- >Top 5. How is the requirements document organized?
Completeness in the requirements document is obtained by using separation of
concerns to obtain the following sections:
- (1) Computer Specification: a specification of the machines
on which the software must run. The machine need not be
hardware, for some software this section might simply be
a pointer to a language reference manual;
- (2) Input/Output Interfaces: a specification of the interfaces
that the software must use in order to communicate with
the outside world;
- (3) Specification of Output Values: for each output,
a specification of its value in terms of the state and
history of the system's environment;
- (4) Timing Constraints: for each output, how often, or
how quickly, the software is required to recompute it;
- (5) Accuracy Constraints: for each output, how accurate
it is required to be.
- (6) Likely Changes: if the system is required to be easy
to change, the requirements should contain a definition
of the areas that are considered likely to change. You
cannot design a system so that everything is equally easy
to change. Programmers should not have to decide which
changes are most likely.
- (7) Undesired Event Handling: the requirements should
also contain a discussion of what the system should do
when, because of undesired events, it cannot fulfil its
full requirements. Most requirements documents ignore those
situations; they leave the decision about what to do in
the event of partial failures to the programmer.
It is clear that good software cannot be written unless
the above information is available.
|
- 5. 要件定義書はどのように構成されるのか？
要件定義書の完全を期すためには、以下の綱目について個別に規定することが重要である。
- (1) コンピュータの仕様：ソフトウェアを走らせるマシーンの仕様。
- (2) 入出力インターフェイス：ソフトウェアが外部と通信するためのインターフェイスの仕様
- (3) 外部の値の仕様：各出力に関して、システム環境の状態や経緯を含めた値の仕様
- (4) 時間的制約：各出力に関して、ソフトウェアはその再計算の頻度、スピードが求められる。
- (5) 正確性の制約：各出力に関しての正確度が求められる。
- (6) 想定される変更：システムが簡単に変更される場合を想定して、変更を検討しなければならなくなる領域の定義を明記すること。すべての変更について同じように簡便に対応できるシステムを設計することが不可能である。プログラマはその変更が起こりやすいかを決める必要はない。
- (7) 想定外の事象への対応：想定外の事象の場合は要件のすべての満たすことはできないので、その場合システムはどうすべきかを考慮しておくべき要件を規定する。多くの要件定義書はこのことを無視し絵いる。プログラマの一部の失敗の場合にどう対処すべきかの規定を放ってある。良いソフトウェアは上記情報がなければうまく書けない
|
>Top
- B. Design and
document the module structure
Unless the product is small enough to be produced by a single
programmer, one must give thought to how the work will be divided
into work assignments, which we call modules.
- The document
that should be produced at this stage is called a module
guide. It defines the responsibilities of each of the modules
by stating the design decisions that will be encapsulated
by that module.
- A module may consist of sub-modules, or it
may be considered to be a single work assignment. If a module
contains submodules, a guide to its substructure is provided.
- A module guide is needed to avoid duplication, to avoid gaps,
to achieve separation of concerns, and most of all, to help
an ignorant maintainer to find out which modules are affected
by a problem report or change request. If it is kept up-to-date,
this document, which records our initial design decisions,
will be useful as long as the software is used.
- If one diligently applies "information hiding" or "separation
of concerns" to a large system, one is certain to end
up with a great many modules. A guide that was simply a list
of those modules, with no other structure, would help only
those who are already familiar with the system.
- The module
guide should have a tree structure, dividing the system into
a small number of modules and treating each such module in
the same way until all of the modules are quite small.
|
- B. モジュール構造を設計し記述すること。
成果物が一人のプログラマによって作成されるような小さい場合を除いて、作業はモジュールと呼ばれるものに分割することを想定しなければならない。
- この段階で作成される文書はモジュールガイドと呼ばれる。それは各モジュールによってカプセル化される設計内容を規定することで、各モジュールの責任範囲を決める。
- モジュールはサブモジュールを含むか、または、単独の役割とみなされるかいずれかである。モジュールがサブモジュールを含む場合は、その構造について規定される。
- モジュールガイドは重複や乖離、関連事項の分断を避けなければならない。とりわけ事情の分からない保守をする人がどのモジュールが問題や変更箇所に関連するのかを見つけやすくしなければならない。この文書が改訂され続けることで、その記録は当初の設計規定を、そのソフトウェアの長い利用期間に亘って役立つ。
- もし熱心に、情報を隠したり、関連事項を分断して大規模システムにすると、非常に多くのモジュールにならざるを得ない。これらのモジュールに対する単なるリストであって、その構造を記述がなければ、そのシステムに精通している人だけを支援になってしまう。
- モジュールガイドはツリー構造をなして、システムを小さな多数のモジュールに分割して、非常に小さなモジュールとして同様に扱えるようにすべきである。
|
- C. >Top Design and document the module interfaces
Efficient and rapid production of software requires that the
programmers be able to work independently. The module guide
defines responsibilities but it does not provide enough information
to permit independent implementation.
- A module interface specification
must be written for each module. It must be formal and provide
a black box picture of each module. Written by a senior designer,
it is reviewed by both the future implementors and the programmers
who will use the module.
- An interface specification for a module
contains just enough information for the programmer of another
module to use its facilities, and no more. The same information
is needed by the implementor.
- While there will be one person or small
team responsible for each specification, the specifications are actually
produced by a process of negotiation between implementors, those who
will be required to use it, and others interested in the design, e.g.,
reviewers.
- The specifications include:
- (1) A list of programs to
be made invokable by the programs of other modules, (called "access
programs").
- (2) The parameters for those access programs.
- (3) The externally-visible effects of these access programs.
- (4) Timing constraints and accuracy constraints, where necessary.
- (5) Definition of Undesired Events.
- In many ways this module specification is analogous to the requirements
document. However, the notation and organisation used is
more appropriate for the software-to-software interfaces that is the
format that we use for the requirements.
|
- C. モジュールのインターフェイスを設計し記述すること。
効率的なソフトウェアの生産のためには、多くのプログラマが独立して作業を進められるようにしなければならない。モジュールガイドは責任について規定するが、独立での構築を許すまでの十分な情報は規定しない。
- モジュールインターフェイスの規定は各モジュールに記載されなければならない。それは形式的であり、各モジュールをブラックボックス的に規定する。シニア設計者によって記載されたものは、このモジュールを利用する将来のプログラマによってレビューされることになる。
- モジュールのインターフェイスの記載は他のモジュールのプログラマが活用するに十分な情報があるべきでそれ以上である必要はない。同じ情報は、モジュール作成リーダ
(インプリメンテイタ)にとっても必要となる。
- また各仕様に関して一人あるいは小グループが責任がある場合は、仕様は実際にはそれを活用するリーダや設計に関与したレビューア間の交渉で決まる。
- その仕様には以下を含む。
- (1) 他のモジュールプロジェクトによって呼び出されるプログラムリスト
- (2) それらのアクセスプログラムのパラメータ
- (3) これらアクセスプログラムの外部から見える効果
- (4) 必要に応じて時間的制約、正確度の制約
- (5) 想定外の場合の規定
- 多くの点で、このモジュール仕様は要件定義書に似ている。しかし、表記方法や利用される組織は、ソフトウェア同士の要求を満たすインターフェイスに特化している。
|
- >Top D. Design and document the uses hierarchy
The "uses" hierarchy can be designed once we know
all of the modules and their access programs.
- It is conveniently
documented as a binary matrix where the entry in position
(A,B) is true if and only if the correctness of program A depends
on the presence in the system of a correct program B.
- The "uses" hierarchy
defines the set of subsets that can be obtained by deleting
whole programs and without rewriting any programs. It is important
for staged deliveries, fail soft systems, and the development
of program families.
- The "uses" hierarchy
is determined by the software designers but must allow
the subsets specified in the requirements document.
|
- D. 活用の階層構造を設計し記述すること。
活用ヒエラルヒーは、すべてのモジュールおよびアクセスプログラムを知り得てから初めて設計可能となる。
- それは便利なようにバイナリーマトリックスで記述される。即ち、プログラムAがプログラムBのシステム上にある場合に限り、A、Bの入力位置は真となる。
- 活用ヒエラルヒーは、プログラム全体を消去して何かのプロジェクトを書き換えるしないで得られるサブセットを定義する。それは段階的な納入や、ソフトウェアシステムが失敗した時、あるいはプログラムファミリーを開発する際に重要となる。
- 活用ヒレらルひーは、ソフトウェア設計者によって決定されるが、要件定義書に規定したサブセットを許容しなければならない。
|
- >Top E. Design and document the module internal structures
Once a module interface has been specified, its implementation
can be carried out as an independent task except for reviews.
- However, before coding the major design decisions are
recorded in a document called the module design document.
This document is designed to allow an efficient review of
the design before the coding begins and to explain the intent
behind the code to a future maintenance programmer.
- In
some cases, the module is divided into submodules and the
design document is another module guide, in which case
the design process for that module resumes at step B above.
- Otherwise, the internal data structures are described;
in some cases, these data structures are implemented (and
hidden) by submodules.
- For each value returned by the module
to its caller, another mathematical function, the abstraction
function, is provided. This function maps the values of
the data structure into the values that are returned.
- For
each of the undesired events, we describe how we check
for it. Finally, there is a "verification",
an argument that programs with these properties would satisfy
the module specification. The decomposition into and design
of submodules is continued until each work assignment is
small enough that we could afford to discard it and begin
again if the programmer assigned to do it left the project.
- Each module may consist of one or more processes. The process
structure of the system is distributed among the individual
modules. When one is unable to code in a readable high-level
language, e.g., if no compiler is available, pseudo-code
must be part of the documentation. It is useful to have the
pseudo code written by someone other than the final coder,
and to make both programmers responsible for keeping the
two versions of the program consistent.
|
- E. モジュールの内部構造を設計し記述すること。
一端、モジュールインターフェイスが仕様決定したら、その構築は、レビューの場合を除き、独立したタスクとして実施される。
- しかし、コーディングの前に、主要な設計上の決定は、モジュール設計文書に記録される。この文書は、コーディングが始まる前に、設計の効率的なレビューおよび将来の保守プログラマのためにコードの背後にある意図を記載するために準備される。
- ある場合には、モジュールはサブモジュールに分割されるので設計文書はもう一つのモジュールガイドとなる。その場合は、当該モジュールの設計プロセスは上記Bのステップを踏む。
- そうでない場合は、内部データ構造が記述され、ある場合にはこれらのデータ構造はサブモジュールで実行（背後で)される。
- モジュールでコーラーに返される各値は、別の数学的関数 (アブストラクション関数)が用意される。この関数は、データ構造の値を、戻しの値にマッピングする。
- 想定外のことを発生する都度、そのチェック法を記載する。最後に検証がある。これらの特性をもつプログラマがモジュール仕様を満たすかどうかの議論である。サブモジュールに分解することの設計は各作用が十分小さくすることで、もし担当したプログラマがそのプロジェクトを去っても手当できるようにする。
- 各モジュールは一つ以上のプロセスからなる。システムのプロセス構造は個々のモジュール間に分配される。ある一つが高レベル言語でコード化できない場合、例えば、コンパイラがない場合は、仮コードで文書を埋めておく。もし最終のコード再生者でない誰かの仮コードを使うのも有効であって、それは両方のプログラマにとっては、２つのバージョンのプログラムを矛盾なく維持する責任がでてくる。
|
- >Top F. Write Programs
- After all of the design and
documentation has been carried out, one is finally ready to write
actual executable code. Because of the preparatory work, this goes
quickly and smoothly. The code should not include comments that
are redundant with the documentation that has already been written.
It is unnecessary and makes maintenance of the system more expensive.
Redundant comments increase the likelihood that the code will not
be consistent with the documentation.
|
- F. プログラムを書くこと。
- すべての設計と文書化が完了した後、ようやく実行コードを書く準備ができる。準備作業ができているので、すばやくかつスムーズに進められる。コードにはコメントは文書の中にすでに書かれているので含める必要はない。それは不必要であり、またシステムの維持費が高くなるだけである。余分なコメントは、そのコードが文書と一致しない可能性を増やすことになる。
|
- >Top G. Maintain
- Maintenance is just redesign and
redevelopment. The policies recommended here for design must
be continued after delivery or the "fake" rationality
will disappear. If a change is made, all documentation that
is invalidated must be changed. If a change invalidates a design
document, it and all subsequent design documents must be faked
to look as if the change had been the original design. If two
or more versions are being maintained, the system should be
redesigned so that the differences are confined to small modules.
The short term costs of this may appear high, but the long
term savings can be much higher.
|
- G. 維持すること
- 維持とは再設計であり再開発である。設計のためのここで推奨したことは納入後も、また見なしの合理性が消えるまで続けなければならない。もし変更される時は、無効になったすべての文書も変更されなければならない。もし設計文書の変更がなされないと、その後の設計文書は元の設計文書のままと見間違えられる。２つ以上のバーションが保持される場合、システムは再設計されることにより、その差分は小さなモジュールに閉じこめられる。このための短期的なコストは高く見えるが、長期的には節約される分の方が遙かに大きい。
|
>Top 6. What is the
role of documentation in the process?:
- A. What is wrong with most documentation today? Why
is it hard to use? Why isn't it read?
It should be clear that documentation plays a major role
in the design process that we are describing. Most programmers
regard documentation as a necessary evil, written as an afterthought
only because some bureaucrat requires it. They don't expect
it to be useful. This is a self-fulfilling prophecy; documentation
that has not been used before it is published, documentation
that is not important to its author, will always be poor documentation.
Most of that documentation is incomplete and inaccurate but
those are not the main problems. If those were the main problems,
the documents could be easily corrected by adding or correcting
information. In fact, there are underlying organisational problems
that lead to incompleteness and incorrectness and those problems,
which are listed below, are not easily repaired:
- (1) Poor organisation.
Most documentation today can be characterised
as "stream of consciousness", and "stream of execution". "Stream
of consciousness" writing puts information at the point
in the text that the author was writing when the thought occurred
to him. "Stream of execution" writing describes the
system in the order that things will happen when it runs. The
problem with both of these documentation styles is that subsequent
readers cannot find the information that they seek. It will
therefore not be easy to determine that facts are missing,
or to correct them when they are wrong. It will not be easy to
find all the parts of the document that should be changed when
the software is changed. The documentation will be expensive
to maintain and, in most cases, will not be maintained.
- (2) Boring
prose.
Lots of words are used to say what could be said by
a single programming language statement, a formula or a diagram.
Certain facts are repeated in many different sections. This
increases the cost of the documentation and its maintenance.
More importantly, it leads to inattentive reading and undiscovered
errors.
- (3) Confusing and inconsistent terminology.
Any complex system
requires the invention and definition of new terminology. Without
it the documentation would be far too long. However, the writers
of software documentation often fail to provide precise definitions
for the terms that they use. As a result, there are many terms
used for the same concept and many similar but distinct concepts
described by the same term.
- (4) Myopia.
Documentation that is written when the project
is nearing completion is written by people who have lived with
the system for so long that they take the major decisions for
granted. They document the small details that they think they
will forget. Unfortunately, the result is a document useful
to people who know the system well but impenetrable for newcomers.
|
6. プロセスにおけるドキュメントの役割とは何か？:
- A. 今日の多くの文書に見られる間違いは何か。それはなぜ使いにくいのか？なぜ読まれないのか？
ここで述べているごとく設計プロセスにおいて文書は重要な役割を演じていることは明らかである。ほとんどのプログラマは文書化を、一部の完了が要求する後知恵として書かざるを得ない必要悪と見なしている。彼らは文書が役立つものとは期待していない。これは的中する予言である。文書は出版前は利用されてこなかったし、文書は著者にとって重要なものでもなく、常にお粗末な文書である。ほとんどの文書は不完全で不正確だが大きな問題にならなかった。もしそのことが大問題であれば、文書はすぐ追加訂正によって正すことができたはずであｒ。実際、底流には組織的な問題があり、それが不完成や不正確さを生んでおり以下述べるように簡単には改めることが難しい。
- (1) お粗末な組織
今日の多くの文書は、「意識の流れ」や「実行の流れ」を特徴としている。「意識の流れ」という書き方は、テキスト中の情報は考えが著者に浮かんだ時点で書かれるものである。「実行の流れ」という書き方は事象が発生する順番でシステムに関して記述するものである。これらの文書化のスタイルの問題は、その後の読者が自分の求める情報を見つけられないということである。それゆえ、事実の記載漏れを見つけたり、または間違った記載を訂正するのは容易ではない。ソフトウェア変更された時に、文書中のすべての訂正箇所を見つけるのは難しい。文書は維持するのに費用がかかり多くの場合、維持されなくなる。
- (2) 退屈な文章
単純なプログラム言語や公式や表での表現できることに多くの単語が費やされている。ある事実が多くの違うセクションで繰り返されている。このことが文書と維持のコストを高めている。重要なことには、そのことが注意散漫となりエラーを見つけにくくしている。
- (3) 混乱し矛盾に満ちた用語
どの複雑なシステムでも、新たな用語を考案し定義が必要となる。それなしには文書はずっと長文になる。しかし、ソフトウェア文書の著者はしばしば使用する用語についての正確な定義を行っていない。その結果、同じ概念が多くの用語が表現される一方で、異なる概念が同じ用語で表現される。
- (4) 視野の狭さ
プロジェクトが完了間近になって書かれる文書は、そのシステムに長く関わり、主な決定は当たり前のように行ってきた人によって書かれる。彼らは忘れてならないと思う詳細の部分を文書にする。不幸にして分社はそのシステムを知っている人には役立つものの、新たな人には分かりづらい。
|
- >Top B. How can one avoid these problems?
- Documentation
in the ideal design process meets the needs of the initial
developers as well as the needs of the programmers who come
later. Each of the documents mentioned above records requirements
or design decisions and is used as a reference document for
the rest of the design.
- However, they also provide the information
that the maintainers will need. Because the documents are used
as reference manuals throughout the building of the software,
they will be mature and ready for use in the later work. The
documentation in this design process is not an afterthought;
it is viewed as one of the primary products of the project.
Some systematic checks can be applied to increase completeness
and consistency.
- One of the major advantages of this approach to
documentation is the amelioration of the Mythical Man Month
effect. When new programmers join the project they do not
have to depend completely on the old staff for their information.
They will have an up-to-date and rational set of documents
available.
- "Stream
of consciousness" and "stream of execution" documentation
is avoided by designing the structure of each document. Each
document is designed by stating the questions that it must
answer and refining the questions until each defines the content
of an individual section.
- There must be one, and only one,
place for every fact that will be in the document. The questions
are answered, i.e. the document is written, only after the
structure of a document has been defined.
- When there are several
documents of a certain kind, a standard organisation is written
for those documents. Every document is designed in accordance
with the same principle that guides our software design: separation
of concerns. Each aspect of the system is described in exactly
one section and nothing else is described in that section.
- When documents are reviewed, they are reviewed for adherence
to the documentation rules as well as for accuracy. The resulting
documentation is not easy or relaxing reading, but it is not
boring. It makes use of tables, formulae, and other formal
notation to increase the density of information.
- The organisational
rules prevent the duplication of information. The result is
documentation that must be read very attentively but rewards
its reader with detailed and precise information. To avoid
the confusing and inconsistent terminology that pervades
conventional documentation, a system of special brackets and
typed dictionaries is used. Each of the many terms that we
must define is enclosed in a pair of bracketing symbols that
reveals its type. There is a separate dictionary for each such
type.
- Although beginning readers find the presence of !+terms+!,
%terms%, #terms#, etc., disturbing, regular users of the documentation
find that the type information implicit in the brackets makes
the documents easier to read.
- The use of dictionaries that
are structured by types makes it less likely that we will define
two terms for the same concept or give two meanings to the
same term. The special bracketing symbols make it easy to institute
mechanical checks for terms that have been introduced but not
defined or defined but never used.
|
- B. これらの問題はどうしたら回避できるか
- 理想的な設計プロセスの文書は、当初の開発者のニーズと同時にその後のプログラマのニーズをも満たさなければならない。上記の各文書は要求綱目の記録や当初の設計で決めたことを記載し、残りの設計の参考文書として使用される。
- しかしまた、文書は維持者が必要とする情報も含まなければならない。文書はソフトウェア構築の参考マニュアルとして利用され、成熟して、その後の作業でも利用される。設計プロセスにおける文書は後知恵であってはならない。それはプロジェクトの主要な成果物の一つと見なされる。システムチェックすることでより完全で矛盾のないものになっていく。
- 文書化に対するこのアプローチの優位な点としては、神話的になっている人月効果の改善につながる点である。新たなプログラマがプロジェクトに参加する場合、彼らは情報を古手のスタッフに完全い依存しないですむ。彼らは最新の合理的な文書を入手できるからである。
- 「意識のながれ」と「実行の流れ」の文書については、各文書の構造を設計することで避けられる。各文書は質問に対して回答するように設計されており、質問を精緻にすることで各セクションの内容が定義されていく。
- 文書中では各事実について記載されるのは唯一箇所でなければならない。質問は回答され、文書は記載されるが、それは文書の構造がきまってからである。
- ある種の文書がいくつか存在する時には、これらの文書に関して標準組織が記載される。各文書はソフトウェア設計をガイドする同一の原則に従って設計される。システムの各側面は一つのセクションに記載され、それ以外のことは記載されない。
- 文書がレビューされる時は、その正確度と共に文書化ルールに準拠しているかレビューされる。その結果、文書化は簡単ではなく、また読みやすくもないが、退屈ということもない。表や式、その他の形式的な表記法を利用して情報の中身を濃密にする。
- 組織的なルールは、情報の重複を防ぐ。その結果、文書は非常に注意して読み込まれなければならないが、その分、読者には詳細かつ正確な情報が伝わる。従来の文書にありがちな混乱や矛盾に満ちた用語を避けるために、特殊な括弧や辞書が使われる。多くの用語は各々括弧で囲まれタイプされる。これはそれぞれの辞書となる。
- 初心者の読者は、!+terms+!,
%terms%, #terms#などが混乱を招くが、通常の文書の読者はこの括弧のタイプは文書をより読みやすくしているのに気づく。
- 辞書の使用はタイプに取って構造化しており、同じ概念を二つの用語にしたり、または同じ用語に違う概念で表現したりしない。この特殊な括弧のシンボルは、利用されたものの定義されなかったり、定義されたが利用されなかった用語を機械的にチェックする手助けとなる。
|
>Top 7. Faking the ideal
process:
- The preceding describes the ideal process that we would like
to follow and the documentation that would be produced during
that process.
- The process is "faked" by producing the
documents that we would have produced if we had done things
the ideal way. One attempts to produce the documents in the
order that we have described.
- If a piece of information is
unavailable, that fact is noted in the part of the document
where the information should go and the design proceeds as
if that information were expected to change. If errors are
found, they must be corrected and the consequent changes in
subsequent documents must be made.The documentation is our
medium of design and no design decisions are considered to
be made until their incorporation into the documents. No matter
how often we stumble on our way, the final documentation will
be rational and accurate.
- Even mathematics, the discipline
that many of us regard as the most rational of all, follows
this procedure. Mathematicians diligently polish their proofs,
usually presenting a proof very different from the first one
that they discovered. A first proof is often the result of
a tortured discovery process. As mathematicians work on proofs,
understanding grows and simplifications are found. Eventually,
some mathematician finds a simpler proof that makes the truth
of the theorem more apparent.The simpler proofs are published
because the readers are interested in the truth of the theorem,
not the process of discovering it. Analogous reasoning applies
to software.
- Those who read the software documentation want
to understand the programs, not to relive their discovery.
By presenting rationalised documentation we provide what they
need.
- Our documentation differs from the ideal documentation
in one important way. We make a policy of recording all of
the design alternatives that we considered and rejected. For
each, we explain why it was considered and why it was finally
rejected. Months, weeks, or even hours later, when we wonder
why we did what we did, we can find out.
- Years from now, the
maintainer will have many of the same questions and will find
his answers in our documents. An illustration that this process
pays off is provided by a software requirements document written
some years ago as part of a demonstration of the ideal process.
- Usually, a requirements document is produced before coding
starts and is never used again. However, that has not been
the case for. The currently operational version of the
software, which satisfies the requirements document, is still
undergoing revision.
- The organisation that has to test the
software uses our document extensively to choose the tests
that they do. When new changes are needed, the requirements
document is used in describing what must be changed and what
cannot be changed.
- Here we see that a document produced at
the start of the ideal process is still in use many years after
the software went into service. The clear message is that,
if documentation is produced with care, it will be useful for
a long time. Conversely, if it is going to be extensively used,
it is worth doing right.
|
7. 理想的なプロセスもどきをもっともらしくするには：
- 我々が行おうとしている理想的なプロセスとそのプロセス中に作成される文書についていままで述べてきた。
- もし我々が理想的なやり方で進め作成した文書をそれらしく見せるためプロセスがある。一つは今まで述べたような順番で文書化することである。
- もし一部の情報が入手できない場合は、文書の部分にその旨記載しておき、その情報が後で得られて変更されるという前提で設計を進捗させる。もしエラーが見つかれば、それらは訂正され、その後の文書に影響する変更もされなければならない。文書は設計のメディアであって、文書に記載されるまではいかなる設計上の決定もなされないと見なされる。どんなにつまずこうと、最終的な文書は合理的でかつ正確なものになる。
- 数学においても、この原則は、最も合理的なものと見なされて、このやり方に従ってきた。数学は熱心にその証明が吟味され、提出される証明は当初発見されたものとは非常に異なる場合が多い。最初の証明は、苦しんだ発見のプロセスの結果であることはよくある。数学者が証明に取り組む中で、理解が増し、簡潔さが発見される。その結果、一部の数学者は、法則の真理を明らかにするようなより簡潔な証明を見出す。簡潔な証明が公表され、読者はその定理が発見されたプロセスではなく、その真実性に興味をもつ。同様のことがソフトウェアにも言える。
- ソフトウェア文書を読む人々はプログラムを理解したいのであって、その発見を追体験したいのではない。合理的な文書を提示することによって、彼らが必要とするものを提供するのである。
- 我々の文書は理想的な文書とは重要な点で異なる。我々は検討したが拒否された設計上の選択肢のすべてを記録するという方針をもっている。我々はその各々について、なぜそれが検討され、なぜそれが最終的に拒否されたのかを説明する。幾月か、幾週か、あるいは数時間後、我々は自分のやったことに疑問を生じれば、それを見つけることができる。
- 今から何年後か、維持者が多くの同じ質問を持ち、我々の文書の中に解答を探すことになろう。このやり方の一つの実例が、理想的なプロセスのデモの一部として何年も前に書かれた要件定義書によって得られたとすれば、それだけで割に合うことになる。
- 通常は、要件定義書はコーディングが開始される前に作られ、再び利用されることはない。しかし、ここでは違う。今、動いているソフトウェアのバージョンは、要件定義書を満たしており、現在進行中のバージョンなのである。
- ソフトウェアをテストしなければならない組織は、何をテストするか選択するために我々の文書を広く活用する。新たな変更が生じれば、要件定義書も何が変更され、何が変更されないのか記述される。
- ここで理想的なプロセスの開始時点で作成される文書は、ソフトウェアのサービス開始後何年も利用されることを見てきた。明確なメッセージとして、もし文書が細心の注意で作られるとすれば、それは長期間役立つものになる。反対に、広範に利用されるとすれば、それは正しく記載されていることを示す。
|
>Top 8. Conclusion:
- It is very hard to be a rational designer; even faking that process
is quite difficult. However, the result is a product that can be
understood, maintained, and reused. If the project is worth doing,
the methods described here are worth using.
|
8.
結論:
- 合理的な設計者になることが至難である。そのプロセスをそう見なすことでさえ容易ではない。しかし結果としての成果物は理解され、保守され、再利用可能なものであるべきである。もし案件が遂行するに値するのであれば、そこで記述された方法もまた利用価値があるのである。
|