Professional Documents
Culture Documents
system has ever been developed in that way, and probably Only if we know which work products are due and what
none ever will. Even the small program developments criteria they must satisfy, can we review the project and
shown in textbooks and papers are unreal. They have been measure progress.
revised and polished’ until the author has shown us what
he wishes he had done, not what actually did happen. V. W H A T Is T H E RATIONAL D ESIGN P ROCESS?
III. WHY Is A D ESCRIPTION OF A R ATIONAL IDEALIZED This section describes the rational, ideal software de-
PROCESS U SEFUL N ONETHELESS ? sign process that we should try to follow. Each step is
What is said above is quite obvious, known to every accompanied by a detailed description of the work product
careful thinker, and admitted by the honest ones. In spite associated with that step.
of that we see conferences whose theme is the software The description of the process that follows includes nei-
ther testing nor review. This is not to suggest that one
design process, working groups on software design meth-
should ignore either of those. When the authors apply the
ods, and a lucrative market for courses purporting to de-
process described in this paper, we include extensive and
scribe logical ways to design software. What are these
systematic reviews of each work product as well as testing
people trying to achieve?
of the executable code that is produced. The review pro-
If we have identified an ideal process, but cannot follow
cess is discussed in [1] and [ 17].
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 A. Establish and Document Requirements
we mean by “faking a rational design process.” If we are to be rational designers, we must begin know-
Below are some of the reasons for such a pretense: ing what we must do to succeed. That information should
1) Designers need guidance. When we undertake a large be recorded in a work product known as a requirements
project we can easily be overwhelmed by the enormity of document. Completion of this document before we start
the task. We will be unsure about what to do first. A good would allow us to design with all the requirements in front
understanding of the ideal process will help us to know of us.
how to proceed. I) Why do we need a requirements document?
2) We will come closer to a rational design if we try to 1) We need a place to record the desired behavior of the
follow the process rather than proceed on an ad hoc basis. system as described to us by the user; we need a document
For example, even if we cannot know all of the facts nec- that the user, or his representative, can review.
essary to design an ideal system, the effort to find those 2) We want to avoid making requirements decisions ac-
facts before we start to code will help us to design better cidentally while designing the program. Programmers
and backtrack less. working on a system are very often not familiar with the
3) When an organization undertakes many software application. Having a complete reference on externally
projects, there are advantages to having a standard pro- visible behavior relieves them of any need to decide what
cedure. It makes it easier to have good design reviews, to is best for the user.
transfer people, ideas, and software from one project to 3) We want to avoid duplication and inconsistency.
another. If we are going to specify a standard process, it Without a requirements document, many of the questions
seems reasonable that it should be a rational one. it answered would be asked repeatedly throughout the de-
4) If we have agreed on an ideal process, it becomes velopment by designers, programmers and reviewers. This
much easier to measure the progress that a project is mak- would be expensive and would often result in inconsistent
ing. We can compare the project’s achievements to those answers.
that the ideal process calls for. We can identify areas in 4) A complete requirements document is necessary (but
which we are behind (or ahead). not sufficient) for making good estimates of the amount of
5) Regular review of the project’s progress by outsiders work and other resources that it will take to build the sys-
is essential to good management. If the project is attempt- tem.
ing to follow a standard process, it will be easier to review. 5) A requirements document is valuable insurance
against the costs of personnel turnover. The knowledge
IV. WHAT S HOULD THE D ESCRIPTION OF THE that we gain about the requirements will not be lost when
D E V E L O P M E N T P ROCESS T E L L U s ? someone leaves the project.
The most useful form of a process description will be 6) A requirements document provides a good basis for
in terms of work products. For each stage of the process, test plan development. Without it, we do not know what
this paper describes: to test for.
7) A requirements document can be used, long after the
1) What product we should work on next.
system is in use, to define the constraints for future
2) What criteria that work product must satisfy.
changes.
3) What kind of persons should do the work.
8) A requirements document can be used to settle ar-
4) What information they should use in their work.
guments among the programmers; once we have a com-
Management of any process that is not described i n plete and accurate requirements document, we no longer
terms of work products can only be done by mindreaders. need to be, or consult, requirements experts.
PARNAS AND CLEMENTS: RATIONAL DESIGN PROCESS 253
Determining the detailed requirements may well be the step is identifying all of the outputs. The heart of the re-
most difficult part of the software design process because quirements document is a set of mathematical functions
there are usually no well-organized sources of informa- described in tabular form. Each table specifies the value
tion. of a single output as a function of external state variables.
2) What goes into the requirements document? 5) How is the requirements document organized?
The definition of the ideal requirements document is Completeness in the requirements document is obtained
simple: it should contain everything you need to know to by using separation of concerns to obtain the following
write software that is acceptable to the customer, and no sections:
more. Of course, we may use references to existing in- a) Computer Specification: A specification of the
formation, if that information is accurate and well orga- machines on which the software must run. The machine
nized. Acceptance criteria for an ideal requirements doc- need not be hardware-for some software this section
ument include the following: might simply be a pointer to a language reference manual.
1) Every statement should be valid for all acceptable b) Input/Output Interfaces: A specification of the in-
products; none should depend on implementation deci- terfaces that the software must use in order to communi-
sions. cate with the outside world.
2) The document should be complete in the sense that c) Specification of Output Values: For each output,
if a product satisfies every statement, it should be accept- a specification of its value in terms of the state and history
able. of the system’s environment.
3) Where information is not available before develop- d) Timing Constraints: For each output, how often,
ment must begin, the areas of incompleteness should be or how quickly, the software is required to recompute it.
explicitly indicated. e) Accuracy Constraints: For each output, how ac-
4) The product should be organized as a reference doc- curate it is required to be.
ument rather than an introductory narrative about the sys- f) Likely Changes: If the system is required to be
tern. Although it takes considerable effort to produce such easy to change, the requirements should contain a defini-
a document, and a reference work is more difficult to tion of the areas that are considered likely to change. You
browse than an introduction, it saves labor in the long run. cannot design a system so that everything is equally easy
The information that is obtained in this stage is recorded to change. Programmers should not have to decide which
in a form that allows easy reference throughout the proj- changes are most likely.
ect. g) Undesired Event Handling: The requirements
3) Who writes the requirements document? should also contain a discussion of what the system should
Ideally, the requirements document would be written by do when, because of undesired events, it cannot fulfill its
the users or their representatives. In fact, users are rarely full requirements. Most requirements documents ignore
equipped to write such a document. Instead, the software those situations; they leave the decision about what to do
developers must produce a draft document and get it re- in the event of partial failures to the programmer.
viewed and, eventually, approved by the user representa- It is clear that good software cannot be written unless
tives. the above information is available. An example of a com-
4) What is the mathematical model behind the require- plete document produced in this way is given in [9] and
ments specijcation ? discussed in [8].
To assure a consistent and complete document, there
must be a simple mathematical model behind the organi- B. Design and Document the Module Structure
zation. The model described here is motivated by work on
real-time systems but, because of that, it is completely Unless the product is small enough to be produced by a
general. All systems can be described as real-time sys- single programmer, one must give thought to how the work
tems-even if the real-time requirements are weak. will be divided into work assignments, which we call
The model assumes that the ideal product is not a pure modules. The document that should be produced at this
digital computer, but a hybrid computer consisting of a stage is called a module guide. It defines the responsibil-
digital computer that controls an analog computer. The ities of each of the modules by stating the design decisions
analog computer transforms continuous values measured that will be encapsulated by that module. A module may
by the inputs into continuous outputs. The digital com- consist of submodules, or it may be considered to be a
puter brings about discrete changes in the function com- single work assignment. If a module contains submodules,
puted by the analog computer. A purely digital or purely a guide to its substructure is provided.
hybrid computer is a special case of this general module. A module guide is needed to avoid duplication, to avoid
The system that will be built is a digital approximation to gaps, to achieve separation of concerns, and most of all,
this hybrid system. As in other areas of engineering, we to help an ignorant maintainer to find out which modules
can write our specification by first describing this “ideal” are affected by a problem report or change request. If it is
system and then specifying the allowable tolerances. The kept up-to-date, this document, which records our initial
requirements document treats outputs as more important design decisions, will be useful as long as the software is
than inputs. If the value of the outputs is correct, nobody used.
will mind if the inputs are not even read. Thus, the key If one diligently applies “information hiding” or “sep-
254 IEEE TRANSACTIONS ON SOFTWARE ENGINEERING, VOL. SE-12, NO. 2, FEBRUARY 1986
aration of concerns” to a large system, one is certain to by the software designers, but must allow the subsets
end up with a great many modules. A guide that was sim- specified in the requirements document.
ply a list of those modules, with no other structure, would
help only those who are already familiar with the system. E. Design and Document the Module Internal Structures
The module guide should have a tree structure, dividing Once a module interface has been specified, its imple-
the system into a small number of modules and treating mentation can be carried out as an independent task ex-
each such module in the same way until all of the modules cept for reviews: However, before coding the major design
are quite small. For a complete example of such a docu- decisions are recorded in a document called the module
ment, see [3]. For a discussion of this approach and its design document [ 16]. This document is designed to allow
benefits, see [6], [ 15]. an efficient review of the design before the coding begins
and to explain the intent behind the code to a future main-
C. Design and Document the Module Interfaces tenance programmer.
Efficient and rapid production of software requires that In some cases, the module is divided into submodules
the programmers be able to work independently. The mod- and the design document is another module guide, in
ule guide defines responsibilities, but it does not provide which case the design process for that module resumes at
enough information to permit independent implementa- step B above. Otherwise, the internal data structures are
tion. A module interface specification must be written for described; in some cases, these data structures are imple-
each module. It must be formal and provide a black box mented (and hidden) by submodules. For each of the ac-
picture of each module. Written by a senior designer, it is cess programs, a function [10] or LD-relation [14] de-
reviewed by both the future implementors and the pro- scribes its effect on the data structure. For each value
grammers who will use the module. An interface speci- returned by the module to its caller, another mathematical
fication for a module contains just enough information for function, the abstraction function, is provided. This func-
the programmer of another module to use its facilities, and tion maps the values of the data structure into the values
no more. The same information is needed by the imple- that are returned. For each of the undesired events, we
mentor. describe how we check for it. Finally, there is a “verifi-
While there will be one person or small team respon- cation,” an argument that programs with these properties
sible for each specification, the specifications are actually would satisfy the module specification.
produced by a process of negotiation between implemen- The decomposition into and design of submodules is
tors, those who will be required to use it, and others in- continued until each work assignment is small enough that
terested in the design, e.g., reviewers. The specifications we could afford to discard it and begin again if the pro-
include: grammer assigned to do it left the project.
1) a list of programs to be made invokable by the pro- Each module may consist of one or more processes. The
grams of other modules (called “access programs”); process structure of the system is distributed among the
2) the parameters for the access programs; individual modules.
3) the externally visible effects of the access programs; When one is unable to code in a readable high-level lan-
4) timing constraints and accuracy constraints, where guage, e.g., if no compiler is available, pseudocode must
necessary; be part of the documentation. It is useful to have the pseu-
5) definition ‘of undesired events. docode written by someone other than the final coder, and
In many ways this module specification is analogous to to make both programmers responsible for keeping the two
the requirements document. However, the notation and or- versions of the program consistent [7].
ganization used is more appropriate for the software-to-
software interface than is the format that we use for the F. Write Programs
requirements. After all of the design and documentation has been car-
Published examples and explanations include [I], [2], ried out, one is finally ready to write actual executable
[5], [11]. code. Because of the preparatory work, this goes quickly
and smoothly. The code should not include comments that
D. Design and Document the Uses Hierarchy are redundant with the documentation that has already
The “uses” hierarchy [13] can be designed once we been written. It is unnecessary and makes maintenance of
know all of the modules and their access programs. It is the system more expensive. Redundant comments in-
conveniently documented as a binary matrix where the en- crease the likelihood that the code will not be consistent
try in position (A, B) is true if and only if the correctness with the documentation.
of program A depends on the presence in the system of a
correct program B. The “uses” hierarchy defines the set G. Maintain
of subsets that can be obtained by deleting whole programs Maintenance is just redesign and redevelopment. The
without rewriting any programs. It is important for staged policies recommended here for design must be continued
deliveries, fail soft systems, and the development of pro- after delivery or the “fake” rationality will disappear. If
gram families [ 12]. The “uses” hierarchy is determined a change is made, all documentation that is invalidated
PARNAS AND CLEMENTS: RATIONAL DESIGN PROCESS 255
must be changed. If a change invalidates a design docu- 4 ) Myopia: Documentation that is written when the
ment, it and all subsequent design documents must be project is nearing completion is written by people who have
faked to look as if the change had been the original design. lived with the system for so long that they take the major
If two or more versions are being maintained, the system decisions for granted. They document the small details
should be redesigned so that the differences are confined that they think they will forget. Unfortunately, the result
to small modules. The short term costs of this may appear is a document useful to people who know the system well,
high, but the long term savings can be much higher. but impenetrable for newcomers.
find the presence of !+-terms-+!, %terms%, #terms#, the case for [9]. The currently operational version of the
etc., disturbing, regular users of the documentation find software, which satisfies the requirements document, is
that the type information implicit in the brackets makes still undergoing revision. The organization that has to test
the documents easier to read. The use of dictionaries that the software uses our document extensively to choose the
are structured by types makes it less likely that we will tests that they do. When new changes are needed, the re-
define two terms for the same concept or give two mean- quirements document is used in describing what must be
ings to the same term. The special bracketing symbols changed and what cannot be changed. Here we see that a
make it easy to institute mechanical checks for terms that document produced at the start of the ideal process is still
have been introduced but not defined or defined but never in use many years after the software went into service.
used. The clear message is that if documentation is produced
with care, it will be useful for a long time. Conversely, if
VII. F AKING THE I D E A L P R O C E S S it is going to be extensively used, it is worth doing right.
The preceding describes the ideal process that we would
like to follow and the documentation that would be pro- VIII. CONCLUSION
duced during that process. The process is “faked” by pro- It is very hard to be a rational designer; even faking that
ducing the documents that we would have produced if we process is quite difficult. However, the result is a product
had done things the ideal way. One attempts to produce that can be understood, maintained, and reused. If the
the documents in the order that we have described. If a project is worth doing, the methods described here are
piece of information is unavailable, that fact is noted in worth using.
the part of the document where the information should go
and the design proceeds as if that information were ex- ACKNOWLEDGMENT
pected to change. If errors are found, they must be cor- R. Faulk, J. Shore, D. Weiss, and S. Wilson of the Na-
rected and the consequent changes in subsequent docu- val Research Laboratory provided thoughtful reviews of
ments must be made. The documentation is our medium this paper. P. Zave and anonymous referees provided some
of design and no design decisions are considered to be helpful comments.
made until their incorporation into the documents. No
matter how often we stumble on our way, the final docu- REFERENCES
mentation will be rational and accurate. [l] D. L. Parnas, D. M. Weiss, P. C. Clements, and K. H. Britton, “In-
Even mathematics, the discipline that many of us regard terface specifications for the SCR (A-7E) extended computer mod-
ule,” NRL Memor. Rep. 5502, Dec. 31, 1984 (major revisions to NRL
as the most rational of all, follows this procedure. Math- Rep. 4843).
ematicians diligently polish their proofs, usually present- [2] K. H. Britton, R. A. Parker, and D. L. Parnas, “A procedure for
ing a proof very different from the first one that they dis- designing abstract interfaces for device-interface modules,” in Proc.
5th Int. Conf: Software Eng., 1981.
covered. A first proof is often the result of a tortured [3] K. H. Britton and D. L. Parnas. “A-7E software module guide,” NRL
discovery process. As mathematicians work on proofs, Memo. Rep. 4702, Dec. 1981.
understanding grows and simplifications are found. Even- [4] F. P. Brooks, Jr., The Mythical Man-Month: Essays on Software En-
gineering. Reading, MA: Addison-Wesley, 1975.
tually, some mathematician finds a simpler proof that [5] P. Clements, A. Parker, D. L. Parnas, J. Shore, and K. Britton, “A
makes the truth of the theorem more apparent. The sim- standard organization for specifying abstract interfaces,” NRL Rep.
pler proofs are published because the readers are inter- 8815, June 14, 1984.
[6] P. Clements, D. Parnas, and D. Weiss, “Enhancing reusability with
ested in the truth of the theorem, not the process of dis- information hiding, ” in Proc. Workshop Reusability in Program., Sept
covering it. 1983, pp. 240-247.
Analogous reasoning applies to software. Those who [7] H. S. Elovitz, “An experiment in software engineering: The architec-
ture research facility as a case study,” in Proc. 4th Int. Conf Soft-
read the software documentation want to understand the ware Eng., Sept. 1979.
programs, not to relive their discovery. By presenting ra- [8] K. L. Heninger, “Specifying software requirements for complex sys-
tionalized documentation we provide what they need. tems: New techniques and their application,” IEEE Trans. Software
Eng., vol. SE-6, pp. 2-13, Jan. 1980.
Our documentation differs from the ideal documenta- [9] K. Heninger, J. Kallander, D. L Parnas, and I. Shore, “Software re-
tion in one important way. We make a policy of recording quirements for the A-7E aircraft, “NRL Memo. Rep. 3876, Nov. 27,
all of the design alternatives that we considered and re- 1978.
[10] R. C. Linger, H. D. Mills, B. I. Witt, Structure Programming: The-
jected. For each, we explain why it was considered and ory and Practice. Reading, MA: Addison-Wesley, 1979.
why it was finally rejected. Months, weeks, or even hours [l I] A. Parker, K. Heninger, D. Parnas, and J. Shore, “Abstract interface
later, when we wonder why we did what we did, we can specifications for the A-7E device interface module,” NRL Memo.
Rep. 4385, Nov. 20, 1980.
find out. Years from now, the maintainer will have many [12] D. L. Parnas, “On the design and development of program families,”
of the same questions and will find his answers in our doc- IEEE Trans. Software Eng., vol. SE-2, Mar. 1976.
uments. [13] -, “Designing software for ease of extension and contraction,” in
Proc. 3rd Inr. Conf Software Eng., May 10-12, 1978, pp. 264-277.
An illustration that this process pays off is provided by [ 14] -, “A generalized control structure and its formal definition,” Com-
a software requirements document written some years ago mun. ACM, vol. 26, no. 8, pp. 572-581, Aug. 1983.
as part of a demonstration of the ideal process [9]. Usu- [l5] D. L. Parnas, P. Clements and D. Weiss, “The modular structure of
complex systems, ” in Proc. 7th Int. Conf. Software Eng., Mar. 1984,
ally, a requirements document is produced before coding pp. 408-417.
starts and is never used again. However, that has not been [I61 S. Faulk, B. Labaw, and D. Parnas, “SCR module implementation