BSTJ 60: 8. October 1981: Using Documentation as a Software Design Medium. (Hester, S.D.; Parnas, D.L.; Utter, D.F.)

19.1 MB·English

Using Documentation as a Software Design
Medium

By &, D, HESTER, D. L. PARNAS,” and DF. UTTER
(aeasuneit raced March 26. 1981)

‘This article describes 1 suftnare devign method Ins on the
incipten of separetion uf concerns and information hiding. The
principle of separation of cancers ts nsed to structure the devign
documentation, und cnformation hiding ts uset ta gui the internat
lesen of the sfteare. Separation of concerns reine that design
tnjormation be divided into elearty alatint card relatively independ
font documents, The darign documents are the main products of the
nti esign phase, andl are carefllysiractarel f9 (9 expose open
tes, i) expreas sign decisions, and (i enture that information
{recorded in nay that allows #10 be readily retrieved lter
Tifnrmation Aide rnd ta enign software that is easy fo change,
We hase apmtied many element uf the sos mathod tthe devel
opment ofthe No, 2 Service Boatuation Sytem na), amullprocessor
Gato acquisition unt transaction system, Our experiences applying,
the design mathe ave described, and seme racamples ae included.

|. wwrmonueTION

‘This amale degeribonu software design method based on Ue prin
ciples of separation of conneme and information hiding. Software
dleien documentation i the medium osed to py the principles.

The vapeeted heneits of th design mvhed ste a follows

1G) Rose nf change. Srstensfuseians chat are likely eo ehange are

identified and information hiding applied to minimize the anu af
soot affeced by a cnc i hese Tonetions.

Gi) Cntrol of the information biel the funetane ofthe system.
A carcluly sleuctured requirements docamene is ta be maintained
hough he ie of che projet,

1044
ii) Ordering of the development step t0 meet the projet objec
tives, Documentation of the woeful aubseta of the system and the
‘dependencies botwoen the software modules seve co fuide the ached

ling of the development effort

(ish Mading the ngrocrente Detoeen developers explicit. Miu
erstandings ate avoWded and a smoother system intopration is
thleved hy documencing the incerfaces between the eofbrare modules
‘tloividal developer.

‘This article provides an overview of the design method we adapted.
oa particular class of software eystems, and suggest guidelines far
applying the design method. Helated work on softrare deiga meth
tilology hae been reporeed in Hets. 1, 2, and 3.'The Naval Kesearch
Tatratory has reporced elated work ona real-time syavem in Tet. 4
Band 6, Marples and experiences are precenced from our uppliution
ofthat principles (othe design ofthe No.2Seriee Fvaluation System
(us), 4 mullioocemervoslenn performing data acquisition and tana.
sotion fanetons

‘We wil las the key design principles, the proposed dasign eps
tnd wmcinled dociinenls the guidelines for preparing each of the
Alocuments, and Tally, ove experiences in applying the principles,

w ADILEWMA

Weare concerued wich che lemma pose hy the following eo
amen

{Ty most aokvaze projects coding bern too wey, Teporant

dign decinins about tho functions ofthe syslen, che nalare ots
fnusticen wd He watsivablity ave wade ae by-product of he
oving proces and do not rocwive Une ciacionsatenan al reves
thoy deverve

‘When paso pues vested prety phase
toometines called x "concepts pave.” “jee detinison phase,” or
“specification phase”), one woes Hil in Une way of langle rela
‘When actual sont feign begin, the progamnters do no use he
prods of he erler ane and one aa the inpreson ha he tne
Spent nee wasted

"Thone view ate eld by the same designers at diferent (ines in
uhetrearcem Alteran experience wrhout a pelminary design ps
Che ft viewpoit ie eepoued with great vigor. ARar an experience
tric a preliminary desig pase the eecond viewpoint held by mt
retina

"The design method dscibed here attmptsto reals this dilemma
by pacing thatthe pretiminary design phases produce « cass
sRnueured se of docuserts a he main product. "The doeumencs ar
{he menue to expree deegn decisions, not an aerthoughe eo be

1942 THE BELL SYSTEM TECHNICAL JOURNAL, OCTOBER 1981
brie ale che system development is complete, Sine doeumen
fevion is the tain produce ofthe design phase, i i Important and
trun! produced with the game iscplioe nnd are with which code
produced,

‘The principles for organizing the dacomenta are discussed in the
{ollosing sections.

I. OUR KEY DESIGN PRINCIPLES

The method we are advocating for design and documentation
‘ase on the prineplee known we cpavation of concerns’ and infor
mation hiding" Separation of conerenn involves the division of
information aboue a aystem into clearly diatine and reluivly inde
pendent pars. ollwnre system design can be bettar controled ithe
Information in design ocumentatin is divided in aeconunce with
‘eparacion of concerts, The complexity in @ oftware system comes
from che number of details that must be considered."To dv ue johs,
‘he developers mot deal with large amount information describing
‘shat the mater ia to do and ov thet work relates to tho wurk of th
thor developers Af each design dorument concaing pes of inform
Tinn thac ane elerly distinc! ail velatvely indepondene dom Uhe
information contained in other design documenta, thon the wees af
the documents cnn easily determine wich document should cxmiain
the information of iene

‘Bare of chango and enhancement of che softwar yea i lypially
major objective in sdopting « formalived design method. The prin
Ciple informacion hiding con be uve to yuide the structuring of
Software co make apeeife typos of shanges ear to implemen. Inu
‘nation hiding involves eneabitating information likely to change in
‘rlerate sae sofewaro morules. Phir encapsulation fits tho aman.
ff sofeware thi. ruc he modified when 2 change is mutle. The
pssibiity of future change smut he explicitly considered during the
feign procersin order w apply information hiding One cannot foresee
fl pai changes hooraver, by evaluating che posmbiliy uf change
pens. at leat the devises about what is Hkely to charge are made
‘xplicily and one howe beloreband which fonctions ner Maly co be
‘say co charge

‘Separalion of roncemns and information hiding describe the asme
don from lwo perspectives or exemple, to felly separate the Concern
aout the different aspects of eign is equivalene to encapsulating
All elements ofeach aspect wl Ince, hiding the information about
tach aepect, We find viewing some leaves from the porspeuive of
Separation of concen ty Ie helphl while ather issues are beter
Siswed fron che panspective of nfarmtin hing The divin ofthe
foflwace ducumenta ino clonrly delineated arean of coverage is com

SOFTWARE DESIGN 1943,
‘vonintly viewed i sparation of concer areas, the determination
bf the information ea be contained ina software modu i viewed ws

Information hiding

"We disenae a number of applications of these principles in the
reminder ofthe article

1Y, DEFWMON OF TERMS

Before inroducing the proposed desigm method, we define a fow
term wed in the paper. These torms have becn uscd ina varcty of
says in the iterators; however, wo each tho spoeife meaning te

teribed below,
Software aystem

Input data icem

Output data ite

Bent

Function

~ A multiperson (and typically mulaiversion) soR-
‘wore evelopment which i delivered and used

A data iter resived by the pater fom 9 er
for an external hardware device or avelen, AW
{input may be used prompdy in the execution of
scfinction, ws in the case of 0 parameter a use
tntere with Che request fora report, of tay be
‘sored in order influence later operation af the
stem, at fa the case of achedaling information
‘uted te contral later execution of a function,

~A data tem displayed to the users of the ayatom
‘orsent to an external hardware device or system,

"A stil tothe aystem causing a function to
be performed. Events may be intornaly trig
ered upon m changy in the wate of the ejatern
fr thoy may be triggered by signal Irom a ure
fr an external hardware device er ayetem, An
fxample of an intemally ciggered event ia the
match of the clock timo agsinat stored achedul-
‘ng information tat initiates the execution of a
‘imetion

~"Tha algorithms, rules or relationships applied
by tho system in response to eveats in order to
determine the values of one or more output dat,
toms and/or the display of the output data items
to the user. We do mot atempe to fix the ize of
‘a Tunetion at eis point, and discuss both large
‘and small functions. Later, when dealing with
‘module decomposition, we recommend subtivid-
‘ng fanetions until they are amall enough to be
developed by one person in limited period of

1944 THE BELL SYSTEM TECHNICAL JOURNAL, OCTOBER 1481
Module = A piece of wflware and the associated doe
mentation which Loyether contin all the infor
Iution about 20m fnction(a or part of «func
tion. Hash module is small enough to be devel
ped by one perzon in Tiled period of time—
oneraly one to three months.

‘Access routine A plece of sftware in module which can he
invoked by soflmare it other module perform
tome portion of the modules funetons. & sub-
routine in a data base module whieh is used by
Sofeware in other modules to access the dala
tase would be a typical example of an access
routine. An acrese routine ix ool restricted to
being a subrmtine. A macro oF the top level
snfreare onntroling& process (which we call the
featin oop ofa process) evuld lao be an access

Process "A set of ues rucines whoee execution se
(quence is prescribed, Te execution of «process
‘ay overlap in time with the execution of other
procesees in Uhe system, In the No. 2 srs 6
Ihave chooen co restrict the relationship beeween,
tuowles and prootste for aimplicity. A module
floes mot encom the main oop of more than
fone proves The testricion revulta in some
‘Shall module, Int reduce the potential con
fusion in the relationship between modules and

processes

‘A module isthe base unit of development and change in cis design
method, Kech morte is defined according to the bformation-hiding
principle (ie, emtaning al information about some functions) in

brder to localize the eoftware nlfected by a change in a function. The
limitation to ome person doing the development eliminates the nee
for multipersn communiations during the intemal development of
the module, and the time Twvlation restricts the amount of work
pececstry t recode the mole in the event ofa change

"The uml approach to specifying a function i to deseribe inpul,
processing, and output, in that order The above definition of afunction
Jeads to function epecfications organized around the system outputs
‘The values and display of sywteine outputs ave specified in terms of
algorithms, rales, relalonships inputs ad wvente We have found this
proach encourazes more precise specification of eystem functions,
fad reduces the londency to bigs the specification toward w particular
implementation.

SOFTWARE DESIGN 1945
“Table |Software design documents
‘ray ts ae dng ed ow a he

‘Sytem sources Used by each medal

Tet pon [Description af she mbt the requirements which wil be

\. APPLICATION OF SEPARATION OF CONCERNS TO THE DESIGN

Process

We propose dividing the information about the system into the wet
of documents ltd in Table I. This division 3 based on what Wo
believe ae fundamentally soparste voncurns i Ube design of «software
system, These concerns continue wo be relevant Uhroushout the sy
tem’s life so the documents should be kept up ta date

"Tho ralationehip of the proposed document is shown in Fig. 1. The
rows indicate the principal Now of informacion required for the
preparation of each document. Many inputs are, of eoure, necesary
for the preparation ofthe raqiremenna specification; hnwever, diss.
sion of the many sources of informacion in heyend the scape ofthis

oe |)

1
ig teeny of prep dunva

1045 THE BELL SYSTEM TECHNICA! JOURNAL, OCTOBER 1961
article. Several feedback paths exist, but have hoen omitted for sim
plicit

"The module decomposition, module dependency, proces stmeture,
and resource allocation documents elloctvely eonsivute an overview
Of the abftware structure. Sinoe the Ors! drat of each of these docu
nents ean be prepared before ony decisions are made shout the
itmplerentation environment for tho este, the overview provided by
the documenta can provide useful gudanoe in choosing the processor
farchiteclure and operating syecem.

‘One rould propareasngle-design overview document with chapters
ealing with module decompoaition, module dependency, process
Simictue, and resource allocation, Silly, one could have indivi)
Tnodule overview documenta contsiningvoodule interface and module
‘sign chapter; however, care iat Laken to avoid mixing conoems
‘between the chapters in an ovarviow document. We believe the con-
‘ces ee lees Hkely to be mixed if aepurate documents are prepared as
thoven in Table L

“The discussion in the remainder of the paper may appear to repre
sent the design procese az a lnesr progression through the design
ep In fact, experienced developurs know feedback to earlier steps
‘occur repeatelly uring the dosixn process, Wo recognize feedback
Tnuse ceeur, however, the feedbaeke should be recorded In the proper
‘document, For example, medic! ion to the requirements should be
found inthe requirements spacifuntign and notin @ rote in a modal
flign document, We are sure of the price of adhering to this
“dacipine, however, we feel dhl the cat of neglecting ii even higher.

‘We will nexe present the scope, uso, and design considertions for
‘each document. By design congiderstions, we mean guidelines or the
Software design associated with the niep covered by the document.
The guidelines for preparing cach of the doeuments are presented
aver

4.1 Requirements specitation
B19 Scope
“This document, together with the docoments it refers to, should
contain everything one needs to know to bul xn acceptable sofware

‘stem. All rignfieant estemally visible behavior of the software
should be constrained to acceptable altematives in this docure

‘The requiremence specification can bo used both for communicating
‘with the ayntem wer wid co guide the software design, When the
‘aquirements specification hs lee reviewed by the systema users, and
the developers and users wgree on che contents of the document, it ean
serve aa part of a contract. Some of the many uses ofthe document in
uid the software design will be disused in the following sections,

5.1.3 Design consaerations

“Many decisions about the functions ofa system are made during the
preparation ofthe requirements specification. Recommendations are
‘made laer in che paper for structuring the document in a way that
‘coutages systematic resolution ofthe ianuesaarocared with speci
‘ation of the system fimetions, The framework of the requirements
‘specication os incended o simulate addressing requirements bauer
‘early inthe syetem design,

‘Propavation of the requirements sperification should start during
the earliest stages of a project. ‘The document then evolves as the
project proceeds beginning as eather sketchy aeleton and gradually
filling ost uni ie complet. Gaps inthe requirements specification
serve Uo highlight the open ieie

5.2 Module ecomposion document
521 Scope

The module decomposition document records the division of the
softvare syatom into modules,

Te should tll rauders the way the state has been structueed and
direc them to che appropriate component and its documentation. This
‘document should eliminate any need to search through more detailed
‘documents to find oe which one of chose documents coneainaa specific
piece of information

8.2.3 Design considerations

A number of the popular software design metho focus attention
‘on the module decomposition sen” The module decomposition
document could be prepared for a decomposition obtained by any of
‘numberof the popular metho: however, since a major abjecive of
{he design methor! iw elesign for chan, we believe module deco
postion is beet accomplished by applying the principle of information
Iiing”

‘Module decomposition according to the principle of information
hiding invlves systematically hiding in « module all the ioformation
about each function defined in the requirements specification ‘The

ast step in seleting functions to hide should be to examine the
xpscted changes” chapter of the requirements epecification (2ee
‘Table 1) Any fonetion that is Hikely ea change should he hidden in 2
more

1948 THE BELL SYSTEM TECHNICAL JOURNAL, OCTOBER 1081
Aller don Uw denompositin inticaced by the xpected Changes
"hapter af he requirements, sume functions nay ont yet: be aaocinted
‘with mutule, ane many modules may” sill be loo large. We ave
toproached the further selection of fuels be hidden in medals
Fro wo appesing dictions, The Gr. insulvex Aeennpeving the
major funetiona into progressively valle funtion ui we judge the
implementation for. tn be sichin the conseraints we ave set for &
‘modle, For example, a major function of displaying eared data tothe
taans is broken down into w umber af individual parte that can be
independently request. Fach report may then be decomposed io
‘function that concrels dialogue withthe wae, a Function to compute
Suit date, and an ourpot formatting function, As discussed eatin
lll tnaior funetiona ean be dated in ler of the information requined
To-duurrmine the output date items woven with the fonction: eg

th promt tothe une,” "te eu dat ive required fo the
reporg” and “the fortui w the repor

‘Continuing subdivision of x imple function may evencually lend
to eubfunctions thal do tot directs conmel an eutput data iter. We
introduc the nolaliowsl convention of intermediate data items wo
dscrite the interaction between such subfunetions Sobfunetions and
inermediane data ere aro further discussed in Use guidelines latin
the arile for preparing the dau ihans chapter of the yequirements
specification, When faneliun ie sulalivied, the resulting parts abould
be chosen ao chey arv likely wn charge independently:

Anuter appavach oo selecting fanccons ta hide in mudules bt
iduoify common-uae functions from the requirements. One Inoks for
services Dequied reponredy by a majoe function or by several major
Fonetions “Tho commonuse functions are hidden ao they canbe
changed without affecing ler paricnttheayetem. Parexamle, daca
storage and retrieval serices sre aan required throughout a system.
Insupprtnx pore generation system, one might identify acommen
Tunion ennteolling islogue with the user, common data bose coos
fonctions, and x commen on pul-farmatting funetion. Having iden
fied as muny corimoruneTunctiona an possible, ane conserace the
‘major functions from combinations of the common-use functions and
‘whaleversinglese funetions are necessary

‘The approach of ilentifsing common-use funetions as the udvan
tage of exeuring uniformity in the user view uf the svetutn andi
reveos the redundant development of similar funcivns by several
frugrimeiers A dlnadvantage ofthis epproach is that no sna rasior
fanetion cam be completa anil dovelypreent ixromplted ana mmr
of modules hiding commonne functions. On balanoe, we tevor the
flevelopment of modes thal ide comenon-use Functions

‘Mosl experievee sofware developers wil quickly identify x numbur

SOFTWARE DESIGN 1949
‘of common-nvefuoetions that should be hidden in modules, Database
functions, devie interfaces, eutpt fonctions and user interfaces are
‘piel ofthe fanetions tho ail generally be readily Wdentiied During
implementation of Une males, the developers may identify the nced
fr additonal vornnon-une modulen Which can be used by bwo or more
ovelopers Some guidance ia available for Menifying point ecm
‘onsite mevioles however. good communications anon developers
continues taba necessary to avoid the development of the same tools
thy to ov more developers

‘Areas rontines in a movile may be used by several other suduls,
Tor example, portions of @ device handler modulo may be used by a
Gata nequsition module, while other parle may he wl by n sting
tole. Neither of the modules using che doves hurler ould contain
‘ny information about the device since that would all be hidden in the
‘device handles,

"Madule devompesiton involves breaking dowm a multipersen devel-
‘opment into individual work ategnments; therefore, che initial duvor-
position must be refined when the implemencacion effort ean be beter
estimated, If rodulr ie found to vequiee only small development
Hort, we xencrally do nor ery ta merge ic with another module sivec
Unure et a great deal of averhead associated wich having wdtioal
rodulen Tl, on the other hand, a module ia found to require more
development effort than one person ean complete within the alloted
tiie Minit, then ie should be mubdivided inte (wo or more smaller
tnorlulee an deneribed above,

‘Since the decompositiun ix bn on the functions described in the
requirements specification, the decomposition should he independent
ofthe implementation chosen for Use modules, with Une exception that
the amount uf implementation effort mits the sizeof the module.

"The Key elder (a Key i aia hewn the decompnsition
prvcess slo alwayedefine mde i ler of Une information biden
hy che module

15.3 Mocuie sependoncy socument

5.31 Scope
"Thia document apecifes for each modile which acceas tines from
‘other madules i mast uae ta perform ta funetion
52.2 tno

“The medule dependency hiecarchy ieermines which acher modbles
amas: bo available for « module to perfari ile functions therefore, the
Adueuatent enn be wsed to idonrify che modules necessary to provide
the raguird subse (ce, the portion of the spstera co be developed
‘frat if time and saffing imitations prevent developing all lunctous