| Bottom | Home | Article | Bookshelf | Keyword | Author | Oxymoron |


A Rational Design Process

How and why to fake it

Cat: ICT
Pub: 2007
#: 0714b

David L. Parnas, etc.


  1. Introduction:
  2. The search for the philosopher's stone: Why do we want to rational design process?:
  3. Why will a software design "process" always be an idealization?:
  4. Why is a description of a rational idealised process useful nonetheless?:
  5. What should the description of the development process tell us?:
  6. What is the rational design process?:
  7. What is the role of documentation in the process?:
  8. Faking the ideal process:
  9. Conclusion:
  1. Introduction:
  2. 賢者の石探し; なぜ我々は合理的な設計プロセスを必要とするのか?:
  3. ソフトウェア設計プロセスはなぜ常に理想化されるのか:
  4. それでもなお合理的な理想プロセスによる記述が有効である理由:
  5. 開発プロセスの記述は何を意味するのか?:
  6. 合理的な設計プロセスとは何か?:
  7. プロセスにおけるドキュメントの役割とは何か?:
  8. 理想的なプロセスもどきをもっともらしくするには:
  9. 結論:
  • When we implement software, we are proceed two things concurrently; coding and documentation about the system. The former is written by computer language, the latter by natural language.
  • ソフトウェアを作成する場合には、我々は2つのことを同時に進めなければならない。システムについてのコーディングと文書化である。前者はコンピュータ言語で、後者は自然語で記載される。
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.

>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?:

  • We will never see a software project that proceeds in the "rational" way. Some of the reasons are listed below:

    • (1) In most cases the people who commission the building of a software system do not know exactly what they want and are unable to tell us all that they know.
    • (2) Even if we knew the requirements, there are many other facts that we need to know to design the software. Many of the details only become known to us as we progress in the implementation. Some of the things that we learn invalidate our design and we must backtrack. Because we try to minimize lost work, the resulting design may be one that would not result from a rational design process.
    • (3) Even if we knew all of the relevant facts before we started, experience shows that human beings are unable to comprehend fully the plethora of details that must be taken into account in order to design and build a correct system. The process of designing the software is one in which we attempt to separate concerns so that we are working with a manageable amount of information. However, until we have separated the concerns, we are bound to make errors.
    • (4) Even if we could master all of the detail needed, all but the most trivial projects are subject to change for external reasons. Some of those changes may invalidate previous design decisions. The resulting design is not one that would have been produced by a rational design process.
    • (5) Human errors can only be avoided if one can avoid the use of humans. Even after the concerns are separated, errors will be made.
    • (6) We are often burdened by preconceived design ideas, ideas that we invented, acquired on related projects, or heard about in a class. Sometimes we undertake a project in order to try out or use a favourite idea. Such ideas may not be derived from our requirements by a rational process.
    • (7) Often we are encouraged, for economic reasons, to use software that was developed for some other project. In other situations, we may be encouraged to share our software with another ongoing project. The resulting software may not be the ideal software for either project, i.e., not the software that we would develop based on its requirements alone, but it is good enough and will save effort.
    • For all of these reasons, the picture of the software designer deriving his design in a rational, error-free, way from a statement of requirements is quite unrealistic. No system has ever been developed in that way, and probably none ever will. Even the small program developments shown in textbooks and papers are unreal. They have been revised and polished until the author has shown us what he wishes he had done, not what actually did happen.

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) 想定外の事象への対応:想定外の事象の場合は要件のすべての満たすことはできないので、その場合システムはどうすべきかを考慮しておくべき要件を規定する。多くの要件定義書はこのことを無視し絵いる。プログラマの一部の失敗の場合にどう対処すべきかの規定を放ってある。良いソフトウェアは上記情報がなければうまく書けない


  • 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のステップを踏む。
    • そうでない場合は、内部データ構造が記述され、ある場合にはこれらのデータ構造はサブモジュールで実行(背後で)される。
    • モジュールでコーラーに返される各値は、別の数学的関数 (アブストラクション関数)が用意される。この関数は、データ構造の値を、戻しの値にマッピングする。
    • 想定外のことを発生する都度、そのチェック法を記載する。最後に検証がある。これらの特性をもつプログラマがモジュール仕様を満たすかどうかの議論である。サブモジュールに分解することの設計は各作用が十分小さくすることで、もし担当したプログラマがそのプロジェクトを去っても手当できるようにする。
    • 各モジュールは一つ以上のプロセスからなる。システムのプロセス構造は個々のモジュール間に分配される。ある一つが高レベル言語でコード化できない場合、例えば、コンパイラがない場合は、仮コードで文書を埋めておく。もし最終のコード再生者でない誰かの仮コードを使うのも有効であって、それは両方のプログラマにとっては、2つのバージョンのプログラムを矛盾なく維持する責任がでてくる。
  • >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. 維持すること
    • 維持とは再設計であり再開発である。設計のためのここで推奨したことは納入後も、また見なしの合理性が消えるまで続けなければならない。もし変更される時は、無効になったすべての文書も変更されなければならない。もし設計文書の変更がなされないと、その後の設計文書は元の設計文書のままと見間違えられる。2つ以上のバーションが保持される場合、システムは再設計されることにより、その差分は小さなモジュールに閉じこめられる。このための短期的なコストは高く見えるが、長期的には節約される分の方が遙かに大きい。

>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. 結論:

  • 合理的な設計者になることが至難である。そのプロセスをそう見なすことでさえ容易ではない。しかし結果としての成果物は理解され、保守され、再利用可能なものであるべきである。もし案件が遂行するに値するのであれば、そこで記述された方法もまた利用価値があるのである。
  • This thesis is very useful which describes the limit of waterfall methodology in developing software and its practical application from the on-site viewpoint, as well as emphasizing the importance of documentation.
  • 本論文は、ソフトウェア開発のWaterfall法の限界と実際の応用について、開発現場の立場からの記述であり、また特に文書化の重要性を強調しており、非常に参考になる。

| Top | Home | Article | Bookshelf | Keyword | Author | Oxymoron |