Class SWEN 648_SW Maintenance

8/12/2019 Class SWEN 648_SW Maintenance

1/156

Educational MaterialsCMU/SEI-89-EM-1

February 1989

Software Engineering InstituteCa rnegie Mellon Un iversity

P it tsburgh, P ennsylvania 15213

Software Maintenance Exercises

for a Software Engineering

Project Course_______________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________

Charles B. EngleU .S. Army S EI Resident Affiliate

Gary FordSEI Undergraduate Software Engineering Education Project

Tim KorsonClemson University

Approved for public relea se.Distribution unlimited.


2/156

The Software Engineering Institute (SEI) is a federally funded research and development center, oper-ated by Ca rnegie Mellon University under contract with the U nited Sta tes Department of Defense.

The SE I E ducat ion Pr ogram is developing a w ide range of ma teria ls to support softwa re engineeringeducation. These ma teria ls are being made ava ilable to educators throughout the academic, indust ria l,an d government communit ies. The use of these mat erials in a course does not in an y wa y constit ute anendorsement of the course by th e SE I , by C arn egie Mellon University, or by the U nited St a t es govern-ment .

Permission to make copies or derivative works of this document is granted, without fee, provided thatthe copies a nd derivat ive works ar e not ma de or dis tr ibuted for direct commercia l a dvant age, a nd th atall copies and derivative works cite this document by name and document number and give notice thatthe copying is by permission of Ca rnegie Mellon U niversity.

______________________________________________________________________________________

Copyright 1989 by Carnegie Mellon University

______________________________________________________________________________________

This technical report was prepared for the

SE I J oint P rogram Off ice

E S D /AVS1

Ha nscom AFB , MA 01731

The ideas and findings in this report should not be construed as an official

DoD position. It is published in th e interest of scientific a nd technical

informa tion exchange.

Review and Approval

This report ha s been reviewed an d is a pproved for publicat ion.

FOR THE COMMANDE R

Karl Shingler

SE I J oint P rogram Off ice

This w ork wa s sponsored by th e U.S . Depart ment of Defense.


3/156

______________________________________________________________________________________CMU/SEI-89-EM-1 i

Table of Contents

1. Int roduct ion 1

2. S oft w a re Ma intena nce 2

3. The D AS C S oft w a re S yst em 4

4. S oft w a re Ma intena nce E xercises 6

4.1. D evelop D ocument a t ion S t a nda rds 6

4.2. D evelop C onfigura t ion Ma na gement P la n 7

4.3. Inst a ll a nd Test t he D AS C S oftw a re 8

4.4. U pda t e D ocument a t ion a ft er P ort ing 9

4.5. D evelop Regression Test P la ns 10

4.6. D iscrepa ncy Report 1: Unexpect ed C onst ra in t E xcept ion 10

4.7. D iscrepa ncy Report 2: Appa rent P a ra meter Mode E rror 12

4.8. D iscrepa ncy Report 3: F ile Na me Lengt h E rrors 134.9. D iscrepa ncy Report 4: E mpt y Input F ile E rror 14

4.10. D iscrepa ncy Report 5: U nrea cha ble C ode 14

4.11. C ode Review s 15

4.12. C ha nge Request 1: Improved Fla w a nd S t yle Messa ges 16

4.13. C ha nge Request 2: U ser In ter fa ce, Version 1 16



4.16. C ha nge Request 5: Add P a ge H ea ders t o Report s 18

4.17. C ha nge Request 6: Add Line Numbers t o F la w Report s 19

4.18. C ha nge Request 7: Allow U ser-S pecified S t yle P a ra met ers 19

Annota t ed B ibliogra phy 21

Appendix 1. P roject Tea m Roles 24

Appendix 2. D ist r ibut ion D isket t e C ontent s 25

Atta chment 1. Discrepan cy Reports a nd Cha nge Requests

Atta chment 2. DASC Documenta tion

Atta chment 3. Diskette Order Form


4/156


5/156

______________________________________________________________________________________CMU/SEI-89-EM-1 1

Software Maintenance Exercises for a Software

Engineering Project Course

Abstract

Software maintenance is an important ta sk in the sof twa re industry and t hus an

importa nt par t of the educat ion of a softwa re engineer. It ha s been neglected in

education, partly because of the difficulty of preparing a software system upon

wh ich ma intena nce can be performed. This report provides a n operat iona l soft-

ware system of 10,000 lines of Ada and several exercises based on that system.

Concepts such as configuration management, regression testing, code reviews,

an d stepwise abstr action can be taught wit h these exercises.

1. Introduction

Because many i f not most computer science majors go on to careers involving sof tware

development, a project-oriented course in softwa re engineering ca n be very va luable in t he

curriculum. One of the goals of the Undergrad uat e Softw ar e Engineering Educat ion P roject

a t the Software Engineer ing Inst i tute (SEI) is to provide instructors and students with

guidelines and ma terials for such a course.

Toward tha t end, in 1987 the SE I published the t echnical report Teachi ng a Project-I nt ensive

I ntr oduct ion to Software Engineer i ng [Toma yko87b]. This report id entified four differ ent

models for such a course a nd t hen presented deta iled guidelines for one of them, t he large

project team model. This model requires 10 to 20 stu dent s orga nized as a softw a re project

team, with different students playing different roles (such as principal architect , project

admin is t r a to r , con f igura t ion manager , qua l i t y a ssurance manager , t es t and eva lua t ion

engineer, document a tion specialist , and ma intena nce engineer). The inst ructor play s the

role of project ma na ger. The stu dent roles a re defined in Appendix 1.

With such a course structure, not every student w rites code; in fact , very few of the st udents

wr ite code. Inst ead, th e students experience directly or indirectly a ll the aspects of a soft-

ware development project , and that is what makes such a course a sof tware engineer ingcourse rat her tha n simply an adva nced progra mming or group progra mming course.

A long-sta nding difficulty w ith such a course is tha t t here is almost never enough t ime to de-

velop a piece of softwa re from scra tch a nd t hen ha ve the student s do some maintena nce on it .

Many instructors are unaware of the importance and methods of software maintenance, and

they often do not even include the subject in their course syllabus. Even inst ructors who do

wa nt to teach ma intenan ce often cannot devote the t ime to finding or developing a system for

the students to mainta in. Since softw ar e ma intena nce is a fact of life in the softw ar e indus-


6/156

______________________________________________________________________________________2 CMU/SEI-89-EM-1

t ry , i t is important for students to have exper ienced i t and learned some of the known

techniques.

The intent of th is repor t is to make teaching sof tware maintenance more feasible in a

softwa re engineering project course. This report provides a operat iona l softw ar e system,

called the Document ed Ada Styl e Checker (DASC),(described in Section 3); a reasonable set

of documentation for the system; and specific exercises with guidelines for the instructor.

Altogether, th e ma teria ls could be th e ba sis for a semester-long course. In dividua l exercises

might be assigned as part of other courses, including a project course based primarily on new

development.

The softw ar e system is writ ten in Ada . For instructors and student s new to Ada , there is a

great a dvant age in designing a course around maintena nce ra t her tha n new development .

St udents a re able to work on a much larger system, a nd t hus experience many more Ada con-

structs, th an would be the case if they had t o learn t he langua ge in par allel with developing

code. In general, ana lysis is easier tha n synth esis in engineering.

2. Software Maintenance

The t erm softw ar e mai nt enan ce is generally used to mean changing a program in order to

correct errors, improve performance, adapt to a changing environment, or provide new

capabilit ies. Some consider this to be an a buse of the term maintenance and suggest other

terminology, including softwar e evolut ionand post-deployment softwar e suppor t. However,

the term maintenanceis w idely used a nd understood, so we w ill use it here also.

In simple models of sof tware development , such as the common wate r fa l l mode l,

ma intena nce is considered to be an a ctivity sepa ra te an d different from development. Froma softw are engineering sta ndpoint , however, it is bett er to view ma intenan ce as involving the

same activit ies as those of development (such as requirements analysis and specification,

design, implementa tion, and testin g) but performed wit h different const ra ints. The most

significant of those constraints is the existence of a body of code and documentation that

must be incorporated into the new version of the system.

Usua lly the cost of modifying the existing system is less tha n th at of creat ing an entirely new

system w ith the desired new functiona lity . This is the fundamenta l justificat ion for softw are

ma intena nce. However, it is the responsibility of the softwa re project ma na ger to recognize

when this is not the case and tha t t he exist ing system should be ret ired and a new system

produced.

Sw an son defines thr ee cat egories of softwa re ma intenan ce [Sw an son76]:

P erfective: modifications request ed by th e user (usua lly because of chan ging or newrequirements) or by the programmer (usually because of the discovery of a betterwa y to implement pa rt of the system).


7/156

______________________________________________________________________________________CMU/SEI-89-EM-1 3

Ada ptive: modificat ions necessita ted by cha nges in the environment in wh ich theprogram operates ( including t ranspor t ing the program to a dif ferent computersystem).

Corrective: modifications to correct previously und iscovered errors in the progra m.

The exercises in t his report include some in ea ch of these cat egories.

There are relatively few techniques or methods specifically for software maintenance as com-

pared to new softwa re development. There are, however, a few softw a re engineering tech-

niques whose usefulness can be demonstrated especially well through maintenance efforts.

Four tha t w e recommend to instructors an d students a re:

Software Configuration Management

Regression Testing

Code Reviews

St epwise Abstra ction

Softw are configur ati on managementencompasses the disciplines and techniques of initiating,

evaluating, and controlling change to software products during and after the development

process. The students should be required to develop an d a dhere to a softw ar e configurat ion

ma na gement plan a s part of the course. The softw ar e system described in this report con-

sists of approximately 10,000 lines of code (in 63 separately compilable program units) and

nine documents. When the students ar e working on the changes to both program a nd

documenta tion, especially w hen different students ar e working on different cha nges, careful

configur a t ion man a gement is essent ia l to th e project . Therefore one of th e f irst

recommended exerc ises i s the deve lopment o f the con f igura t ion management p lan .

Additional information on configuration management may be found in [Tomayko86] and

[Tomayko87a].

Regr essi on t esti ngis d efined a s selective retesting t o detect faults introduced during m odifi-

ca t ion of a system or system component , to ver i fy tha t modif ica t ions have not caused

unintended adverse effects, or to verify that a modified system or system component st ill

meets its specified requirement s [IE E E83]. Some of the exercises require ma jor chan ges to

the softwa re system a nd th erefore call for substa ntia l retesting, perha ps involving the entire

test suite. Other exercises require rat her minor changes, and a single, simple retest ma y be

sufficient . One of the first recommended exercises is th e development of regression test

plan s. Additiona l informat ion on regression testing m a y be found in [Collofello88b].

Code reviewsoffer an opportunity for software developers to discover errors or inefficiencies

in their code earlier in the development process. Their use is an a pplica tion of a fund a -

menta l principle of engineering: it is almost a lwa ys less costly to find an d correct an error


8/156

______________________________________________________________________________________4 CMU/SEI-89-EM-1

early in t he process ra ther t ha n lat e. They ar e becoming increasingly common in indust ry, so

students s hould learn a t least one form of review in a softw ar e engineering course. Reviews

can be conducted in a number of different ways; a good introduction for the instructor may be

found in [Collofello88a].

Stepwi se abstract i on is a technique pioneered by IBM Federal Systems Division (now

Syst ems Integra tion Division). It is used to recover the high level design of a syst em in the

abs ence of design document at ion. The design ca n then be used to plan progra m chan ges.

Britcher and Craig describe the process as follows [Britcher86]:

From the source code, the designer abstracted the module design and recorded itusing P DL [Process Design Lan gua ge]. Ch oosing the level of a bstra ction based onthe module, the designer determined the change required. Often this wa s anitera t ive process; the designer abstracted a deta i led design from the code, thengenerated a nother less deta iled (yet st ill precise) abst ra ction from tha t design. Theiterat ion continued unt il the designer wa s comfortable with the level of abstra ction.

Some of the exercises in this report can ta ke adva nta ge of this t echnique (for exam ple, exer-

cises 4.16, 4.17, an d 4.18). For the DASC system, w hich is reasonably w ell structured an dma kes good use of Ada packages, th is abstra ct ion is quite st ra ight forwa rd. However , be-

cause it is a powerful a nd useful technique, we strongly recommend using it . The instructor

may want to lead a classroom discussion to introduce the process.

3. The DASC Software System

The Document ed A da Styl e Checker (DASC)software system examines syntactically correct

Ada progra ms a nd reports on t heir adh erence to predefined style conventions. Exa mples of

the style conventions examined are:

Ca se of cha ra cters in reserved w ords a nd object identifiers

Consistency of indenta tion to show progra m control str uctures

U se of bla nk lines t o set off progra m blocks

Subprogra ms t oo short or too long

Control structures or packages nested too deeply

U se or la ck of use of Ada -specific fea tur es


9/156

______________________________________________________________________________________CMU/SEI-89-EM-1 5

The st yle checker produces tw o kinds of reports , called a f lawrepor t a nd a stylereport . The

former identifies specific statements in the program that violate style conventions, and the

lat ter is a qua ntita t ive summary of the progra ms style.

The system w as originally developed on a Da ta G eneral computer system a nd lat er ported to

a D EC VAX VMS syst em. It w as t hen placed in the Ada S oftw a re Repository, and hence in

th e public doma in. (For informa tion on the repository, see [Conn87].)

In the spr ing of 1988, P rof. Linda Rising of Indian a Universi ty-P urdue Universi ty a t F or t

Wa yne (IP FW) selected the syst em as th e basis of a softw a re engineering project course. Her

student s w ere given t he ta sk of porting the syst em to the universitys VAX and providing a

reasonable set of documentation for it (hence the name documentedAda style checker).

The stud ent documenta tion consist s of the followin g document s:

1. Requirements Document

2. P rel iminary Design

3. Deta i led Design

4. Documenta t ion Standa rds and G uidelines

5. C od in g S t a n d a r ds

6. Qua li t y Assurance P lan

7. Tes t P l a n

8. Conf igura t ion Mana gement P lan

9. U s er M a nu a l

The requirements and design documents (items 1-3), having been produced from the source

code, clearly are not as complete as one would expect in a real software development project.

However, they do provide a sta rt ing point for ma intena nce exercises, including ma intenan ce

of the documents themselves.

The documentation and coding standards and the three plan documents (items 4-8) were

used by P rof. Rising a nd her st udents t o guide their project . These documents reflect both

development a nd ma intena nce a ctivit ies. Some of the first exercises in this report involve

updat ing these documents t o reflect new m aint enance activit ies.

The user man ua l (item 9) describes th e use of th e system in its IP FW implementa tion. Much

of this document is s pecific to VAX VMS sy stems a nd some specific to IP FW. P orting the

softwa re to a nother computer syst em will require extensive revision of this document. In

par t icular , por t ing the system wil l require redesign and reimplementa t ion of the user

interfa ce, the description of which constit utes a ma jor part of this document. Some of the

exercises in this report are based on the development of a new user interface (see exercises

4.13, 4.14, a nd 4.15).

In t he summer of 1988, Prof. Rising provided the softw ar e and student documenta tion to the

SE I for further development an d releas e as tea ching support ma terials. P rof. Tim Korson of

Clemson University, wh o was a visit ing scientist a t t he SE I, succeeded in porting t he system

to a VAX VMS sy stem a nd t o a Zenith Z248/MS-DOS syst em running Alsys Ada . He a lso

developed the first ma intena nce exercises. Subsequ ently, Maj. Chuck En gle, a U .S. Army

resident affiliate a t t he SE I, ported th e system to a VAX Ultrix syst em running Verdix Ada ,

a nd he developed some addit ional exercises. SE I sta ff developed oth er exercises, a nd edited

an d forma tted the student documenta tion.


10/156

______________________________________________________________________________________6 CMU/SEI-89-EM-1

It is interesting t o note th at each of the th ree Ada compilers on t he thr ee different computer

systems repor ted a dif ferent set o f errors and wa rnings w hen the program w as compiled.

Although th ey were not reported by a ll compilers, each error ha s been documented a s a dis-

crepancy report and the correction of the error appears in this report as an exercise (see

exercises 4.6 th rough 4.10).

The SEI has prepared distribution diskettes containing the DASC system source code, the

student documenta t ion, tools , and the test suite . These may be ordered in tw o formats,

Macintosh 3.5 800K byte diskettes a nd IB M P C 5.25 1.2M byte diskettes. The documents

are available in three format s: as M icrosoft Worddocuments and MacWr i tedocuments for

the Ma cintosh, and a s text-only documents for any system. A description of the contents of

the distribution diskettes appears in Appendix 2, and a diskette order form appears at the

end of this report .

We assume tha t ma ny users of th is softwa re wil l want to upload the system from a P C t o a

VAX VMS computer sys tem. To help in this process, th e distribu tion diskett es also include

tw o command files tha t can be used to tra nslat e betw een th e relat ively long file names of the

VMS version an d the eight chara cter na mes required under MS-DOS . In ad dit ion, the

diskettes include a file giving the required compilation order of all the program units.

We do not present th is art ifact a s a model of good coding st yle, design, or document a tion. In

fact , if the st yle checker is run on itself , it reports m a ny problems. There are some fairly

obvious design improvements t ha t could be ma de. The documenta tion is rea sonable alt hough

not complete, a nd no formal a na lysis, design, or documentat ion t echnique w as used.

In summary, one might say that this art ifact seems to be a fairly representative example of

existing softwa re systems. This is not necessarily ba d, because a valid educational objective

might be to expose students to the real world.

4. Software Maintenance Exercises

The exercises described in this section are presented in roughly the order in which they

migh t be a ss igned to the s tudents . Most of the exercises , however , a re re la t ive ly

independent, and instructors should feel free to select those that are most appropriate for

their pa rticular courses.

We recommend th a t t he first five exercises, which deal w ith project ma na gement, be included

in a ll courses. In m ost cases, these exercises can be assigned to different st udents or groups

of students, t hose playing the roles of documenta tion specialist , configuration ma na ger, test

and evaluat ion engineer , and ver if ica t ion and val ida t ion engineer (see Appendix 1 fordescriptions of these roles).

Exercises 4.6 through 4.10 are presented as di scr epancy r eport s and exercises 4.12 through

4.18 as chan ge r equests. These reports a nd requests, forma tt ed as one page forms, appear in

Att achment 1 an d also on the distribution diskett es. We recommend th at instructors ta ilor

these to their circumstances, print copies, and submit them to the student Change Control

B oard for action. The project leader and the configurat ion ma na ger can ass ign responsibility

for ma king the a ppropriat e changes in th e code an d th e documenta tion.


11/156

______________________________________________________________________________________CMU/SEI-89-EM-1 7

E xercise 4.11 can be used t o introduce the concept of a code r evi ew. The exercise identif ies a

module in th e code for wh ich a careful ins pection should un cover opportunit ies for improving

the code. The result will be an a ddit ional change request . Once the students a re fam iliar

w ith code review, t hey should be asked t o conduct th em for their own code.

4.1. Develop Documentation Standards

Exercise

Select word processing or document processing softwa re to be used t o develop a nd ma inta in

project documenta tion. Tra nsfer the documents from t he distribution diskette to the a ppro-

priate computer system. Modify the document Documentat ion Standar ds and Guid el i nest o

reflect local requirements and capabilities.

Information for Instructors

The objective of this exercise is to introduce the students to the system documentation and to

the idea of maint ain ing documenta tion along with t he code. Too often in the academic en-

vironment, documenta tion is an a fterthought.

It is likely tha t t he instructor will select t he appropriate documenta tion softwa re. If possible,

a llow the st udents t o use the sam e computer syst em for code development a nd documenta-

tion. This can give more of the feel of a n integra ted program ming environment in w hich it is

easy t o manipulate a ll kinds of softw are w ork products in a coordina ted wa y.

In any case, the documentation specialist role should be assigned to a student with good

knowledge of the word processing softwa re being used. The instru ctor should ensure tha t th e

documenta tion stan dar ds developed by the student a re reasonable. Tha t is, adh erence to the

sta nda rds should be easily with in the capabilit ies of all students. An in-class forma l review

of the document can be used t o help identify problems w ith t he sta nda rds.

The documenta tion stand ard s supplied with th e DASC system reflect the fact th at IP FW stu-

dents used Macintosh systems with Ready,Set,Go!and Excelerator software. The documents

themselves w ere prepared for distribution on a Macintosh with M icrosoft Wor dand MacWri te

sof twa re . I f such a system is avai lable , very l i t t le change in the documenta t ion sta ndards

should be required.

Otherwise, we recommend that the text-only versions of the documents be the basis for

project document s. Ma ny more chan ges in the documenta tion sta nda rds will then be re-quired.

Only one or tw o student s a re likely to be involved in th is exercise. Therefore it ca n be done

in parallel with other exercises.


12/156

______________________________________________________________________________________8 CMU/SEI-89-EM-1

4.2. Develop Configuration Management Plan

Exercise

Using t he existing DASC Confi gurati on M anagement Plana s a basis, develop an appropriat e

configurat ion ma na gement plan.


The objective of this exercise is to introduce the students to the basic concepts of configura-

tion management, including the confi gurat ion man agement plandocument and the change

cont r ol boar d. I t is importa nt th at the document be approved and th e cha nge control boar d

be in place before the code ma intena nce exercises be at tempted. This w ill not only help ma ke

the code installation (see the next exercise) more well-defined, but it also helps instill in the

students t he idea of pl an f ir st, execute la ter.

The exist ing plan wil l need only minor modif ica t ions when used in a course in which

different student s pla y different project roles. Some modifications tha t will certa inly be

needed are t he following:

Change the date mentioned in section 2.3.4.

Cha nge the n am es of the project d irectories as needed for your part icular computersyst em. References to these directories appea r in sections 2.3.2, 3.1.3, 3.1.4, 3.2.5,3.3, an d a ppendices 1 a nd 2.

Provide an appropriate list of test and support tools that will be used by the stu-dents . This list is referenced in section 2.3.3.

Ch oose an appropriat e file na me convent ion, as d escribed in section 3.1.5.2.

Ch oose a n a ppropria te file protection convention, as described in section 3.2.6.

4.3. Install and Test the DASC Software

Exercise

Tra nsfer th e source code from the dist ribution diskette to a n a ppropriat e computer sys tem.

Structure the code directory or directories as specified in the configuration management


13/156

______________________________________________________________________________________CMU/SEI-89-EM-1 9

plan. Compile each progra m unit , using t he compilat ion order defined on the distr ibution

diskett e. Record all compiler error a nd dia gnostic messa ges.

Run t he progra m on the entire test suite. Record a ny discrepan cies for considerat ion by the

Cha nge Control B oard.


The objectives of this exercise are to make the software system operational in preparation for

the later exercises and to give the students the experience of trying to install a system that

they ha ve not th emselves writ ten. The absence of a deta iled insta llat ion guide will require

the students t o improvise. The instructor may w ish to have the students wr ite such a guide

for their part icular computer system a fter the insta llat ion.

The DASC source code on the distribution diskette is known to have some errors (see exer-

cises 4.6 through 4.10). Depending on th e Ada compiler used, stud ents m a y discover some of

these known errors (but probably not all of them), and they may also discover some addi-tional errors.

In many cases, the students may see error messages rela ted to wrong compila t ion order ,

typographica l errors in commands, or just misunderstanding of the Ada system they are

using. These errors should be corrected immedia tely so tha t th e inst a llat ion can cont inue.

Er ror an d dia gnostic messages from th e compiler should be recorded a s discrepancy reports.

The reports should be submitted to the student C ha nge Control B oard for action ra ther th an

being corrected immedia tely. Er rors uncovered by runn ing the test suite should also be

recorded as discrepancy reports.

4.4. Update Documentation after Porting

Exercise

Revise all documenta tion as required to reflect t he system a fter insta llat ion on the new com-

puter system a nd to bring all documents into compliance with the documenta tion stan dar ds.


The objective of this exercise is to continue to instill in the students the idea that the docu-

menta t ion is an integra l par t o f the system, and t hat any ma intenance ef for t must include

documenta tion maint enance.

Instructors should take care to ensure that documentation changes are handled like code

changes, meaning that they are considered by the Change Control Board and the configura-

tion mana ger. Note tha t the discrepancy report form and change request form ha ve places

for recording the documentation affected by changes.


14/156

______________________________________________________________________________________10 CMU/SEI-89-EM-1

Some documenta tion revisions w ere detailed in exercise 4.2. Other places w here revisions

will be necessary ar e:

Section 5.1 of the Test Plan mentions the names of the test files and the directory inwh ich they reside. These should be cha nged as r equired by the computer syst embeing used by the st udents.

Modify the user manua l to reflect the user interface, assuming t ha t th e students a renot using t he VAX VMS in terfa ce supplied on th e distribut ion diskette.

This exercise can a lso be used t o correct some known problems w ith t he original d ocument a -

tion distribut ed with t his report . These problems include:

Section 3 of the Test Plan shows the relat ionships between a requirement and thetest case for that requirement. The ta ble mentions only four test cases, w hen in factthere a re seven test ca ses supplied on t he distribution diskette.

T h e D o cu m e n t a t io n S t a n d a r d s a n d G u id e l in e s d e sc r ib e a s t a n d a r d f o rrepresenta tion of a cronym s in document s. This sta nda rd is not follow ed in thedocuments on the dist r ibut ion disket te . Eith er the documents or the standa rdshould be changed.

The Preliminary Design Document and the Deta i led Design Document do notcont a in revision hist ory sections. These should be a dded.

The document a tion specialist will hav e prima ry responsibilit y for this exercise. Oth er

students ma y begin some of the la ter exercises in pa rallel with the documenta tion revisions.

4.5. Develop Regression Test Plans

Exercise

Section 5.2 of the Test P lan document describes how regression t esting is to be performed.

Modify this section as necessary.


The objective of this exercise is to intr oduce th e concept of regression t esting. It is likely tha t

th e st udent s will not ha ve encountered this concept in earlier program ming courses. There-

fore it is important for the instructor to spend some time discussing the reasons for doing

regression testing and the importa nce of ma inta ining the test plan so tha t regression testing

ma y be done properly w hen needed.


15/156

______________________________________________________________________________________CMU/SEI-89-EM-1 11

The student designated to be the project test engineer should have continuing responsibility

to keep section 5.2 of th e test plan up to da te. As new syst em requirement s are a pproved by

th e Cha nge Control Boa rd, the test engineer should also revise section 3 of the test pla n. The

instructor, as project manager, should be responsible for ensuring that this student keeps the

test pla n current. An in-class review of th e par ts of th e test pla n relat ed to regression testingcan be helpful.

4.6. Discrepancy Report 1: Unexpected ConstraintException

Exercise

Dur ing execution, a n exception is ra ised in t he procedure ENTERING_BLOCK_STRUCTURE.

Identify a nd correct the error tha t caus es this exception to be raised.


The objective of this exercise is to give the stu dents experience correcting a n error th a t r a ises

an exception in Ada. Inst ructors may w an t t o point out tha t t he error causing th is exception

might go undetected in most earlier program ming lan guages.

This is a n a ctual bug t ha t w as discovered w hen porting t he system t o the Alsys compiler on a

P C/AT-clas s ma chine. The problem did not occur in th e VAX VMS/DE C Ada env ironm ent . If

the Alsys compiler is available, the strategy actually used to identify the error, described

below, ma y be useful for students. In other cases, it will be necessa ry for the instr uctor to

identify the exception a nd the sta tement th at causes it to be ra ised.

Since an exception is r aised in awhenotherssta tement, th e first st ep in th e problem is to

determin e which exception is being raised. This is easily a ccomplished by a ddingwhens ta te-

ment s for all possible exceptions. Altern a tively, some compilers provide a wa y to determ ine

th e current exception na me. After doing this, the exception will be identified a s a const ra int

error.

The students are likely to make some common errors when following this strategy, especially

if they ar e new to Ada . The instru ctor might expect the follow ing errors:

If students test forwhenIO_EXCEPTION.anything, they should be sure to add awithIO_EXCEPTIONS;sta tement w hen compiling th e package.

If st udents block off a portion of the program a nd a dd:

EXCEPTION when constraint_error => Put_line(" Error on line xxx ");

consider propagating the exception with:


16/156

______________________________________________________________________________________12 CMU/SEI-89-EM-1

Raise

To identify which statement is causing the constraint error, the procedure can be divided into

blocks, each of w hich ha s its own exception ha ndler. The block conta ining t he error ca n th en

be subdivided into smaller blocks until th e stat ement causing th e error is identified. Tha t

sta tement w ill be found to be:

CURRENT_STATUS.PROCEDURE_NEST_LEVEL := CURRENT_STATUS.PROCEDURE_NEST_LEVEL +1

This approach to the exercise requires a knowledge of the classical d iv ide-and-conquer

debugging strategy, and how to use the Alsys compiler, but does not require an in-depth

knowledge of Ada . A brief introduction to th e synta x and sema nt ics of exception ha ndling in

Ada a long with access to a reference manual should be suff icient for an exper ienced

programmer.

A constraint error indicates that the variable is being given a value that is not valid for its

type. B eca use the new value is the former va lue plus one, the former va lue must be

incorrect . An examina tion of all references to this varia ble will show tha t it a nd tw o other

rela ted var iables are never init ia l ized. Ea ch of these var ia bles (PACKAGE_NEST_LEVEL,

CONTROL_NEST_LEVEL, and PROCEDURE_NEST_LEVEL) is used as a nesting level counter,

and each should star t a t 0.

Once the student s ha ve determined how these var iables are used, they must d etermine how

an d where to init ia lize them. All three ar e fields in the varia ble CURRENT_STATUS, wh ich is

declared in procedure STYLE_CHECKER. An exam inat ion of that procedure shows tw o wa ys

to accomplish the initialization.

The first wa y is to wr ite assignment sta tements in t he body of the procedure:

CURRENT_STATUS.PACKAGE_NEST_LEVEL := 0;CURRENT_STATUS.CONTROL_NEST_LEVEL := 0;CURRENT_STATUS.PROCEDURE_NEST_LEVEL := 0;

The second way is to give default initial values to these fields in the declaration of the record

type itself:

type STATUS_RECORD is record ... PACKAGE_NEST_LEVEL : TOKENIZER.LINE_INDEX_RANGE := 0; CONTROL_NEST_LEVEL : TOKENIZER.LINE_INDEX_RANGE:= 0; PROCEDURE_NEST_LEVEL : TOKENIZER.LINE_INDEX_RANGE:= 0; ...end record;


17/156

______________________________________________________________________________________CMU/SEI-89-EM-1 13

4.7. Discrepancy Report 2: Apparent Parameter ModeError

Exercise

The compiler reports that ou t mode parameters in two procedures are not given values.

Determine whether this error is a result of the parameters modes being incorrectly specified,

wh ether those para meters are not needed at all , or whether the para meters should ha ve been

given values in the bodies of the procedures. In t his lat ter case, supply the code to give the

para meters appropriate values.

The errors a re reported for procedures CREATE_DICTIONARYand TOKEN_IS_FOUND, both of

wh ich a re defined in package DICTIONARY_MANAGER.

Information for InstructorsThe objective of th is exercise is to give th e stud ents experience in a situa tion w here th e origi-

nal developers of the code wrote some obviously unusual code but did not document their

rea sons for doing so. In th is ca se, th e stu dents should deduce tha t the developers were

leaving a hook for a ddit iona l functionality tha t w as n ever ad ded.

The code for the pa ckage in q uestion is:

package body DICTIONARY_MANAGER is

procedure CREATE_DICTIONARY(DICTIONARY_KIND : in DICTIONARY_TYPE; DICTIONARY_IN : out DICTIONARY_PTR;

FILENAME : in STRING) is begin return; end CREATE_DICTIONARY;

procedure TOKEN_IS_FOUND(IN_DICTIONARY : out DICTIONARY_PTR; WORD : in TOKEN_DEFINITION.TOKEN_TYPE; FOUND : out BOOLEAN) is begin FOUND := TRUE; end TOKEN_IS_FOUND;

end DICTIONARY_MANAGER;

It is appar ent th a t t he procedure bodies are just stubs. References to these tw o procedures

appear in procedures STYLE_CHECKER a n d CHECK_OBJECT_NAMES_SIZE . U pon closer

examination of the package and these references, it can be determined that the dictionary

manager package is for purposes of automatic spelling correction, a feature not currently

present in th e style checker. One of the references is seen in th is code segment (from t he

la tt er procedure):

DICTIONARY_MANAGER.TOKEN_IS_FOUND(STYLE_DICTIONARY, SPELL_CHECK_WORD, FOUND);


18/156

______________________________________________________________________________________14 CMU/SEI-89-EM-1

if not FOUND then -- Not handled now... null; end if;

There are tw o str a ight forwa rd solutions to th is exercise. The first is to give values to the outmode pa ra meters (which can be any thin g, since th ey are never used). This preserves the op-

tion of addin g the spelling correction ca pability la ter . Appropriat e comments in th e code

would be useful for subsequent m aint ainers.

The second solution is t o remove all th e relat ed code. This is th e more interestin g solution

becau se it forces the stud ents t o examine more code to be sure tha t t hey ha ve found a ll the

related code, and it also demands more thorough regression testing to determine that the

existing functionality of the system has not been compromised.

4.8. Discrepancy Report 3: File Name Length Errors

Exercise

Dur ing th e process of tra nsporting t he DASC syst em to the MS -DOS /Alsys Ada environment ,

a l l system f i les with n am es exceeding 8 chara cters were given modif ied nam es. U pon

execution, th e system could not find s ome files because they h a d different na mes. The sys-

tem should be modified to w ork with the new 8-chara cter nam es.


The objective of this exercise is to correct known errors in t he syst em a nd to give the stu-dents a n introduction to the Ada fa cilit ies for relat ing externa l and interna l file names. This

exercise is essent ia l for students using MS-DOS; i t probably can be ignored by other

students.

The instructor ma y simply a sk th e students to find a ll occurrences of file na mes in t he code

an d reduce them t o 8 chara cters if necessar y. The following a re known occurrences and ma y

be given to the students if desired.

In t he specification of pa ckage FILE_HANDLING:

HELP_FILE_NAME : constant STRING := "STYLE_HELP.INI"; STYLE_DICTIONARY_NAME : constant STRING := "STYLE_DICTIONARY.INI";

In the body of package FILE_HANDLING:

COMMAND_LINE_FILE_NAME : constant STRING := "COMMANDLI.TXT";


19/156

______________________________________________________________________________________CMU/SEI-89-EM-1 15

4.9. Discrepancy Report 4: Empty Input File Error

Exercise

If the file input file (named COMMANDLI.TXTin t he origina l version of the sy stem) is empty

or any line in th at file is the na me of a nonexistent file, several exceptions a re raised a nd th e

DASC sy stem fa ils to perform properly. Modify th e system to provide better ha ndling of

th ese conditions.


The objective of this exercise is to let the students see the result of incompleteness in the

specifica tion. Of course, since the original requirement s specifica tion is not a va ilable, we

cannot be sure that th is is a specif ica t ion error ra ther than a design and implementa t ion

error. H owever, such bound a ry condit ion errors a re commonly overlooked in specifica tions,so it is likely to be such an error.

It is desirable tha t t he system ma ke a gra ceful exit if the list of files to process is empty, a nd

tha t it simply report files tha t can not be found a nd proceed to the next. The students s hould

revise the requir ements d ocument to cover these cases. Then th e code should be modified to

reflect the new requirements. Regression testing sh ould follow, a nd th e test suite should be

augm ented to include the case of an empty COMMANDLI.TXTfile.

4.10. Discrepancy Report 5: Unreachable Code

Exercise

The compiler reports unreachable code in function IS_STATEMENT. Determine the cause of

this error a nd correct it .


The unreachable code is tha t shown below between the t wowhenclauses:

case TOKENIZER.TYPE_OF_TOKEN_IS(EXAMINED_TOKEN) is ...

when WHILE_TOKEN => return true; LOOKAHEAD := PREVIOUS_NON_TRIVIAL_TOKEN(EXAMINED_TOKEN); if TOKENIZER.TYPE_OF_TOKEN_IS (LOOKAHEAD) /= TOKENIZER.END_TOKEN then return true; else return false; end if; when ACCEPT_TOKEN => return true;


20/156

______________________________________________________________________________________16 CMU/SEI-89-EM-1

...end case;

The inst ructor w ill need to identify t he unrea chab le code unless t he compiler does so. This

discrepancy w a s noted using t he VAX Ult rix/Verdix Ada environment , but not w ith t he other

environments in w hich the system wa s tested.

The unrea chable code can simply be removed. The reas on for its presence is unknown .

4.11. Code Reviews

Exercise

In conjunction with exercise 4.10, conduct a code inspection of procedure is_statement.


The objective of this exercise is to introduce students to the fundamentals of code reviews.

Such reviews (walkthroughs and inspections) are among the most important tools available

to softw a re engineers for improving softw a re qua lity. The instruct or should require code re-

views of all ma jor chan ges to the code. (For more informat ion on a ll kinds of softw ar e tech-

nical reviews see [Collofello88a] and [Cross88].)

To introduce the process, th e stud ents a re a sked to conduct a code review of an existing code

module. Procedure is_statementha s been chosen for tw o reasons. First , it is t he subject

of a discrepancy report (see exercise 4.10) and a code review is a good technique for

determining how to remove this discrepancy.

Second, the procedure exhibits several occurrences of a common coding error and the review

can be used to generate a n a ddit ional chan ge request t o fix them. The error is a misuse of

the boolean da ta type, as illustrat ed in this code segment from the procedure:

if TOKENIZER.TYPE_OF_TOKEN_IS (LOOKAHEAD) /= TOKENIZER.END_TOKEN then return true;else return false;end if;

The im proved code is:

return TOKENIZER.TYPE_OF_TOKEN_IS(LOOKAHEAD) /= TOKENIZER.END_TOKEN;


21/156

______________________________________________________________________________________CMU/SEI-89-EM-1 17

4.12. Change Request 1: Improved Flaw and StyleMessages

Exercise

Spelling errors have been noticed in th e flaw a nd st yle reports generat ed by DASC; th ese are

to be corr ected. The errors ar e:

1. Inconsista nt Indenta tion should be Inconsistent Indenta tion

2. P RAGMAS and P RAG MAs should be P RAG MAS

3. Reserve word . . . should be Reserved word . . .

4. upper case sh ould be uppercase; lower ca se should be lowercase


This is a very sim ple perfective ma intena nce exercise. It s objective is to let the stud ents ga in

some familiar ity wit h the packages tha t generate the reports. This familiarit y will be useful

for subsequent exercises.

B eca use the specific errors to be corrected are given, t he student s should be a ble to use the

sea rch capa bility of a t ext editor to find the occurrences of these errors. The only difficulty is

identify ing the packa ges a nd procedures to be sear ched. They are pa ckage REPORT_-

GENERATORa nd procedure RESERVE_WORD_ENCOUNTERED .

4.13. Change Request 2: User Interface, Version 1

Exercise

Currently the DASC system expects the list of file names to be processed to be in the file

named COMMANDLI.TXT. Add a new user interface tha t , upon sta rt ing the system, prompts

the user for a f i le name, reads in that f i le name, and then reads the names of f i les to be

processed from tha t file.


The objective of this exercise is to introduce the students to writ ing entirely new code in

response to a r equest for new functiona lity. This is the first of three exercises devoted to in-

creased functionality of the user interface.

Note tha t t he user int erface supplied on t he distr ibution diskett e for th e VAX VMS/DE C Ada

environment is writ ten in DEC Command Language (DCL), and is therefore not portable to

a ny other environment . This an d the next tw o exercises essentia lly provide th e functiona lity

of that user interface, but coded in Ada .


22/156

______________________________________________________________________________________18 CMU/SEI-89-EM-1

When doing these three exercises, the instructor may wish to assign them sequentially to

introduce the students to the i terat iv e enh ancement techniq ue for syst em building. Although

originally int ended for n ew development, th is technique is equa lly applicable t o maint enance

when a significant amount of new code is being produced.

This exercise will allow students new to Ada to gain some familiarity with simple string

input and output , and with making a correspondence between internal and external f i le

names.

These exercises should include the wr it ing of more deta i led specif ica t ions and the

modification of documenta tion as a ppropriat e. Of particular int erest is the modificat ion of

the test plan . The new user interface ca n only be tested intera ctively, so the test pla n will

need to contain a description of how this is to be done. The user ma nua l will a lso require a

subst a ntia l modification (see also exercise 4.4).


Exercise

Modify t he user int erface of th e previous exercise so tha t the us er can build th e file of file

na mes interactively. The systems should repeat edly prompt the user for a nother file name,

read t he nam e, and a ppend it to the file of file na mes. The user should be given a wa y to

indicat e tha t no more na mes are to be read, a t w hich t ime the DASC system processes those

files w hose names ha ve been read.

Information for InstructorsThis exercise continues th e development described for the previous exercise. The inst ructor

should require the students to prepare a more detailed specification of the changes to be

ma de and require appropriat e changes to documenta tion, including the user manua l. The

section of the test plan describing interactive testing (see previous exercise) may need to be

revised.


Exercise

Modify the user interface to allow imm ediate screen display of flaw an d style reports. After

processing all the files whose names are in the input file (named COMMANDLI.TXT in the

original version of th e system), the sy stem should a sk the user if display of the flaw report is

desired. If so, it is displayed on the screen one page a t a t ime (like the UNI X or MS -DOS

more comma nd). After each page, the user ca n request another page or exit . A simila r

display of the style report s hould then be a llowed. This is repeat ed for each file processed.


23/156

______________________________________________________________________________________CMU/SEI-89-EM-1 19


The objective of this exercise is to give the students an opportunity to add a significant new

capability to the system. It w ill give the students a subst an tia l a mount of experience wit h

interactive input and output in Ada.

As with the previous two exercises, the instructor should first require a detailed specification

of the proposed change. This should include the w ording of messages from th e system a nd

the responses tha t t he user may give. The user manua l describes this kind of interface, an d

it ma y be used as a sta rt ing point for the new specificat ions.

Documenta tion will aga in need to be modified. If the user ma nua l wa s stripped of all refer-

ences to th e origina l VAX VMS user interfa ce as a result of exercise 4.4, the st udents m ay

now discover tha t t hey ar e putting almost a ll of the removed ma terial ba ck in. Therefore it is

importa nt for the instru ctor to structure the exercises so as not to frustra te the student s un-

necessa rily. One approach is to do the th ree user interfa ce modifica tion exercises sequen-

t ia l ly but w ith the understan ding that the user manua l wil l be modif ied only once, and t hat

will be to reflect th e fina l user interfa ce. The actua l modifica tion of the user manua l ca nprecedeth e code changes, so that the ma nua l can serve as a specificat ion for the design of the

new code.

4.16. Change Request 5: Add Page Headers to Reports

Exercise

Revise the format of flaw reports and style reports to include a page heading on each page.

The heading sh ould include the na me of the Ada progra m file tha t genera ted th e report , t heda te, and t he report page number.


The objective of this exercise is to give the st udents experience read ing a nd un dersta nding a n

existing code module, and t hen ma king a relat ively small change.

The pa ckage REPORT_GENERATOR conta ins the procedures tha t produce th e reports. A rec-

ommended approach to a solut ion is to add a procedure that formats and pr ints a page

heading, count th e lines printed, a nd t hen invoke the pa ge heading procedure at the a ppro-

priate points. St udents might a nticipat e that different printer or display devices would have

different num bers of lines per pa ge, and so it is good pra ctice to ma ke the page size a na medconsta nt th at can be easily cha nged.


24/156

______________________________________________________________________________________20 CMU/SEI-89-EM-1

4.17. Change Request 6: Add Line Numbers to FlawReports

Exercise

Revise the forma t of the fla w report so tha t t he source file line number is reported for each

line found to ha ve a style flaw .


The objective of this exercise is also to give students experience in understanding a code

module in order to make a sim ple chan ge. The cha nge needed is sma ller tha n tha t of the pre-

vious exercise, but requires more program analysis.

The difficult t ask is understa nding t he organizat ion of the progra m a nd t he function of eachof its components so tha t st udents can determine where to ma ke the required modifications.

As the style checker processes the code, it builds a linked list that it can then traverse in

either direction. B ecause of this, source lines with fla ws a re sometimes reported out of order.

Recognizing this behavior of the program is essential to finding a solution for this exercise.

An analysis of the source code reveals that the program already keeps track of the current

line number in th e varia ble CURRENT_TOKEN.TOKEN_POSITION.LINE. Since this var iable

is visible in t he procedure LINE_CONTAINING_TOKEN, and t his procedure is alwa ys used to

produce the source line reported in the flaw report , one simple solution is to modify this

procedure so that it concatenates the line number onto the beginning of the erroneous source

line.

The instr uctor might expect th e student s to ma ke the following errors on this exercise:

I t is easy t o end up with a type mismat ch when dealing with integers, st r ings, anddynamic st r ings a l l in the same sta tement .

The code contains a number of variables that keep track of different but relatedcounts, such as statement count, number of blank lines, and line within the file.St udents could print out t he wrong varia ble.


25/156

______________________________________________________________________________________CMU/SEI-89-EM-1 21

4.18. Change Request 7: Allow User-Specified StyleParameters

Exercise

Modify the system so that the quantifiable style parameters are read from a file rather than

being directly coded into th e syst em. This will allow different orga niza tions to customize the

system m ore easily.


The objective of this exercise is make a significant change to the system that will increase its

usefulness. I t requires tha t t he students f irst understand t he var ious sty le para meters and

then decide which can m eaningfully be customized. Then they must identify where those pa-

rameters appear in the code, change constants to variables, and provide a way for values ofthose varia bles to be read in.

The package Style_Parameters , and in particular , procedure Set_Style_Parameters ,

conta ins the code tha t defines the style para meters to be examined. The instructor should

point out that the system is reasonably well designed in this respect ; the students might be

a sked to imagine performing t his exercise on a system in w hich these values a re neither col-

lected in a single package nor declared a s na med consta nts.

Regression testing a fter this m odifica tion should be planned carefully. A first round of tests

should be performed with t he style para meters in th e input file being th e same a s those cur-

rent ly declar ed in the code. This will a llow the new output t o be compared to the known out-

put from the test suite. Then the va rious para meters should be cha nged, the tests performed

aga in, and the output examined. Many of the results will be different, and t he students must

determine manua lly if they are correct .

It will certa inly be the case tha t for some values of some par am eters, no program in t he cur-

rent test suite is an a dequate test . New test program sh ould be devised and placed in the

test suite.

As w ith t he previous cha nges, modificat ions of the documenta tion will be required. St udents

should not forget tha t t he user man ual w ill require revision as pa rt of this exercise.


26/156

______________________________________________________________________________________22 CMU/SEI-89-EM-1

Annotated Bibliography

[B r i t ch er 86] B r i t ch er , Rob er t N ., a n d J a m es J . C r a ig. U s in g M od er n D es ig n P r a c t ices

to Upgrade Aging Softwa re Systems. IE EE Software 3, 3 (Ma y 1986),

pp. 16-24.

Th is paper descr i bes some softwar e ma i nt enance exper i ences w i th i n

IBM .

[C ol lofell o88a ] C ol lofell o, J a m es S . The Softwa r e Techni cal Revi ew Pr ocess. Curriculum

Module SEI -CM-3-1.5, S oftwa re E ngineering Inst itut e, Ca rnegie Mellon

Un iversity, P it tsburgh, P a., 1988.

Capsul e Descri pti on: Th is modul e consists of a compr ehensive

exam in ati on of th e techn ical r evi ew pr ocess in th e softwa r e devel-

opment and m ai nt enan ce li fe cycl e. Formal r evi ew meth odologies ar e

anal yzed in detai l fr om the perspective of t he review part icipan ts,pr oject man agement an d softwar e qual it y assur ance. Sampl e r eview

agend as ar e al so pr esent ed for common t ypes of r evi ews. T he objec-

ti ve of the modul e is to provide the stu dent w it h th e in form ati on

necessar y to pl an and execute hi ghl y eff i cient an d cost effecti ve

techn i cal reviews.

[C ol lof el lo88b ] C ol lof el lo, J a m es S . I ntr oduction to Softw are Veri f ication and Vali dati on.

Curr iculum Module SEI-CM-13-1.1, Sof tware Engineer ing Inst i tute ,

Ca rnegie Mellon U niversity, Pit tsburgh, P a., 1988.

Capsu le Descr ip t ion : Sof tw ar e ver i f i ca t i on and va l i da t ion

techn iques are in t roduced and the i r app l i cab i l i t y d i scussed.

Appr oaches to in tegr ati ng t hese techn iqu es int o compr ehensi vever i f i ca t ion and va l id a t i on p lans are a lso addr essed. Th is

cur ri cul um modul e provides an overvi ew needed t o understand in -

depth curr iculum modules in the veri f ication and val i dati on ar ea.

[C onn87] C on n , Rich a rd. Th e Ada Soft war e Reposit ory an d t he Defense Dat a

Network. New York: New York Zoetr ope, 1987.

Th is book descr i bes th e hi story and cont ent s of the Ada Softw ar e

Reposi tor y (th e ori gin al sour ce of th e DA SC system ). I t also

descr i bes severa l w ays for i nt er ested per sons to access th e r eposit ory

and extr act softwar e fr om it.

[C ross88] C ross, J ohn A., edit or . Support M ater i a ls for T he Softw are Techni cal

Review Pr ocess. Support Materia ls SE I-SM-3-1.0, Softwa re Engineering

Inst itute, Ca rnegie Mellon University, Pit tsburgh, P a., 1988.

Th is package in clud es a number of exampl es and str uctu r ed exer -

cises for stud ent s.


27/156

______________________________________________________________________________________CMU/SEI-89-EM-1 23

[IE E E 83] I E E E . Standar d Glossary of Sof twar e Eng in eer i ng T erm in ology.

ANSI /IE EE St d 829-1983, Ins tit ute of Electrical a nd E lectronics En gi-

neers, 1983.

Thi s book shoul d be avai la ble for r eference by all softwa re engi neer -in g edu cator s and students. Al th ough some per sons mi ght d isagree

wi th some of t he defi ni ti ons, on th e wh ole it is an excell ent r esour ce

for th ose wi shin g to pr omote a stan dar d vocabul ar y of softw ar e

engineering.

[P a rikh83] P a r ikh , G ir is h, a n d N ich ola s Zveg in tzov . Tu to r i a l on So f twa re

Maintenance. IE EE Computer Society P ress, 1983.

Thi s book i s a coll ection of over t hi r ty papers on softwa r e mai nt e-

nan ce, mostl y from t he lat e 1970s and ear ly 1980s. M uch of th e

ma ter ia l i s now dated, but on t he wh ole it is some in ter estin g back-

ground r eadin g for the instructor.

[S w a nson 76] S w a n s on , E . B . Th e D im en si on s of M a in t en a n ce. Proc. 2nd

I nt er nat ional Confer ence on Softw ar e En gin eer in g, IEEE Computer Soci-

ety , 1976, pp. 492-497.

Th is is one of the ver y ear ly papers on softw ar e mai nt enan ce. I t i s

stil l often cit ed f or some of i ts defi ni ti ons.

[Toma yko86] Tom ayko, J a mes E . Suppor t M ater i a ls for Sof tw are Conf i gura t i on

Management. Support Ma teria ls SE I-SM-4-1.0, Softw a re En gineering

Instit ute, Ca rnegie Mellon U niversity, Pit t sburgh, P a., 1986.

Th is package of support mat er ial s inclu des a number of exampl es of

in du str ial di screpancy r epor ts and change forms, an exampl e of a

confi gur ati on management pla n, sever al k in ds of classr oom m ateri -

als, and exampl e of using a confi gur ati on m anagement tool, an d

addi ti onal background mat eri al for instru ctors.

[Tom a yko87a ] Tom a yko, J a m es E . Softw ar e Configur ati on M anagement . Curriculum

Module SEI -CM-4-1.3, S oftw a re E ngineering Ins titut e, Ca rnegie Mellon

Un iversity, P it tsburgh, P a., 1987.

Capsul e Descri pti on: Softwar e conf igu r ati on management encom-

passes th e di scipl in es and techni ques of ini ti ati ng, eval uat in g, and

cont r oll i ng change to softwar e pr oducts du r in g and aft er t he devel-

opment pr ocess. I t emphasizes the im port ance of conf igu r ati on con-tr ol i n m anaging softw are production.

[Tom a yko87b] Tom a yko, J a m es E . Teachi ng a Project-I nt ensive I ntr oduction to Softw are

Engineer ing. Technical Report C MU /SE I-87-TR-20, Soft wa re En gineer-

ing Instit ute, Ca rnegie Mellon University, Pit tsburgh, P a., 1987.

Abstra ct: Th is repor t i s meant as a gui de to the teacher of th e in tr o-

du ctor y course in softw ar e engi neeri ng. I t cont ain s a case study of a

cour se based on a lar ge pr oject. Ad di ti onal ma ter ia ls used in


28/156

______________________________________________________________________________________24 CMU/SEI-89-EM-1

teachi ng th e cour se and sampl es of stu dent-pr oduced document ati on

ar e al so avai l abl e. Oth er models of cour se organ i zati on are al so

discussed.


29/156

______________________________________________________________________________________CMU/SEI-89-EM-1 25

Appendix 1. Project Team Roles

Pri ncipal Archit ect: Responsible for the creat ion of the softw ar e product. P rima ry responsi-

bilit ies include aut horing the requirements document a nd specifica tion document, a dvising

on overall design, and supervising implementa tion and testing.

Pro jec t Adm in i s t ra to r : Responsible for resource a l locat ion a nd t ra cking. P r ima ry

responsibilit ies a re cost a na lysis an d control, computer a nd hum a n resource acquisit ion an d

supervision. Collects da ta an d issues weekly cost/ma npower consumption reports an d the

final report.

Confi gurat i on M anager: Responsible for change control. P rima ry responsibilit ies include

writ ing t he configura t ion ma nagement plan, t racking change requests a nd discrepancy re-

por ts , ca l l ing and conduct ing change control board meet ings, archiving, and prepar ing

product releases.

Qual it y Assur ance M anager : Responsible for th e overall qualit y of th e released product. P ri-mary responsibilit ies include preparing the quality assurance plan, calling and conducting

reviews an d code inspections, evalua ting documents an d tests.

Test and E valu ati on En gineer: Responsible for testing an d evalua ting individual modules

an d subsystems a nd for prepar ing the appropriate test plans.

Designer: P rima ry responsibility is developing aspects of the design as specified by the ar chi-

tect . Durin g the pre-design sta ge, this person could a ssist in a literat ure search to explore

simila r products or problems.

Implementor: P rima ry responsibility is to implement th e individua l modules of the design

an d serve as th e technical specia list for a part icular la ngua ge an d opera ting system. During

the r equirements specificat ion a nd d esign sta ges, the implementors could develop tools a ndexperiment with new language constructs expected to be needed in the product.

Docum entat ion Special ist: Responsible for the appeara nce a nd clarity of all documentat ion

an d for the creation of user manua ls.

Veri f icat ion and Val i dat ion E ngineer: Responsible for crea ting a nd executing test plans to

ver ify and val ida te the sof tware as i t develops, including t racing requirements through

specifica tion, design, coding, and test ing. Also responsible for code inspections. Acts a s a

member of an independent group.

M ai nt enan ce En gin eer : P rima ry responsibility is creat ing a guide to the maint enance of the

delivered product.

Note: The above definit ions ar e reprin ted from [Toma yko87b].


30/156

______________________________________________________________________________________26 CMU/SEI-89-EM-1

Appendix 2. Distribution Diskette Contents

Macintosh Version

The informat ion on t he source code diskette ha s been ta ken from the Ada Softw ar e Reposi-

tory a nd is in t he public doma in. As a courtesy t o the original developers of the system, it is

requested that all copies of the softw are reta in the prolog either as a separ at e file or a s a pre-

fix to the ma in program .

The informat ion on th e documenta tion diskett e is copyright 1989 by Ca rnegie Mellon U niver-

sity. P ermission to make copies or derivat ive works of this informa tion is gra nted, wit hout

fee, provided that the copies and derivative works are not made or distributed for direct

commercial advantage, and that all copies and derivative works cite this document by name

an d document number a nd give notice tha t the copying is by permission of Ca rnegie Mellon

University.

Source Code Diskette

The diskette name is D A S C S o u r c e , a nd it conta ins a copyright notice file and t hree foldersnamed S o u r c e , T e s t S u i t e , and T o o l s (Figur e 1). A typica l folder display for ea ch is shownbelow.Figure 1. Cont ents of source code diskette

The source code folder (Figure 2) includes 63 Ada compilation units and two input files(c o m m a n d l . t x t and s t y x h e l p . i n i ) tha t a re needed when t he system is executed.


31/156

______________________________________________________________________________________CMU/SEI-89-EM-1 27

Figure 2. Source folder (par tia l listing)

The test s uite folder (Figur e 3) cont a ins seven test files and t wo output files (t e s t 1 . F L W a ndt e s t 1 . S T Y ) produced w hen th e DASC sy stem is r un on file t e s t 1 . a d a .Figure 3. Test Suite folder


32/156

______________________________________________________________________________________28 CMU/SEI-89-EM-1

The tools folder (Figure 4) includes the following files:i n s t a l l . d o c Describes how to insta ll the version of DASC prepared by t heIP FW students. It m akes reference to diskett es used by thestudents; those references do not apply to the distribution

diskettes th at accompany t his report .d a s c . c o m A DE C C ommand La ngua ge (DC L) file tha t is the user interfaceto the DASC system on a VAX VMS computer system.c o m p i l e . d o c A listing of the order in w hich th e 63 source files must becompiled.d w n _ v m s . c o m A DE C C ommand La ngua ge (DC L) file tha t changes the longfile names used on a VMS system to the short (8 character) filena mes for an MS-DOS sys tem.u p _ v m s . c o m A DE C C ommand La ngua ge (DC L) file tha t changes the short(8 character) file names for an MS-DOS system to the long filena mes used on a VMS system.d w n _ u n i x . c o m A UNI X C shell script tha t cha nges the long file names used ona UNI X system to the short (8 chara cter) file na mes for a n MS-

DOS system.u p _ u n i x . c o m A UNIX C shell script tha t cha nges the short (8 cha racter) filena mes for a n MS -DOS system t o the long file names used on aUNIX system.Figure 4. Tools folder

Documentation Diskette

The diskette name is D A S C D o c , and it contains a copyright notice file and a folder namedD A S C D o c u m e n t a t i o n . Tha t folder conta ins thr ee other folders, each of which contains acomplete set of DASC documents in a different format (Microsoft Word, MacWrite, and textonly). A typical folder display is shown in Figure 5.


33/156

______________________________________________________________________________________CMU/SEI-89-EM-1 29

Figure 5. DASC D ocumenta tion and Word Forma t folders

The folder D R s a n d C R s cont a ins t he Microsoft Word versions of the discrepan cy reports an dchange requests tha t a ppear a s At t achment 1 of th is document . These a ppear on l y inMicrosoft Word format .PC/AT VersionThe diskette name is DASC, and it conta ins both the source code a nd the documenta tion. At

the top level it contains a copyright notice file COPRIGHT.TXT and four directories, named

SOURCE, TSTSUITE, TOOLS, and DOCUMENT. List ings of the directories a re shown below.

The informa tion in directories SOURCEand TSTSUITEhas been taken from the Ada S oftw a re

Repository an d is in the public domain. As a courtesy t o the original developers of the sys-

tem, it is requested tha t a ll copies of the softwa re retain the prolog either a s a separa te file or

a s a prefix to the main program. The informa tion in directory TOOLS is a lso in the public

domain, either ha ving come from the Ada Softw ar e Repository or ha ving been placed in the

public domain by Ca rnegie Mellon U niversity.


34/156

______________________________________________________________________________________30 CMU/SEI-89-EM-1

The informa tion in directory DOCUMENT is copyright 1989 by Carnegie Mellon University.

Permission to make copies or derivative works of this information is granted, without fee,

provided that the copies and der iva t ive works are not made or dist r ibuted for direct

commercial advantage, and that all copies and derivative works cite this document by name

an d document number a nd give notice tha t the copying is by permission of Ca rnegie MellonUniversity.

Top Level Directory Listing

Volume in drive A is DASCDirectory of A:\

SOURCE 2-09-89 2:18pTSTSUITE 2-09-89 2:18pTOOLS 2-09-89 2:18pDOCUMENT 2-09-89 2:18pCOPRIGHT TXT 1014 2-09-89 1:01p 5 File(s) 533504 bytes free

Source Directory Listing

Volume in drive A is DASCDirectory of A:\SOURCE

. .. BEGINOFL ADA BUILDTOK ADA CHECKEND ADACHECKFOR ADA CHECKOBJ ADA CHECKSTA ADA CHECKTHE ADA CHECKUNI ADACOMMANDL ADA COMMENTT ADA CURRENTT ADA DYN ADA ENTERB ADAENTERS ADA EXITBL ADA FILESPEC ADA FIXIT ADA GETNEXTT ADAINSERT ADA ISARESER ADA ISSTATEM ADA LINECONT ADA LITERAL ADAMANAGER ADA NEWLINET ADA NEXTCHAR ADA NEXTIDEN ADA NONTRIVI ADAOBJECTNA ADA REPGENBO ADA REPGENSP ADA RESERVDW ADA RESERVEW ADA

SPARAMBO ADA SPARAMSP ADA SRCHBCKO ADA SRCHBCKW ADA SRCHFORE ADASRCHFORW ADA STACKPAC ADA STYLECHE ADA TOKENDEF ADA TOKENZBO ADATOKENZSP ADA TREEROOT ADA TYPEDECL ADA HELPBODY ADA HELPDISA ADAHELPEXIT ADA HELPFB ADA HELPFIND ADA HELPFS ADA HELPGET ADAHELPIB ADA HELPINIT ADA HELPIS ADA HELPME ADA HELPMENU ADAHELPRESE ADA HELPROMP ADA HELPSPEC ADA HELPTEXT ADA FILEBODY ADASTYXHELP INI COMMANDL TXT 67 File(s) 533504 bytes free

Test Suite Directory L isting

Volume in drive A is DASCDirectory of A:\TSTSUITE

. .. TEST1 ADA TEST1A ADA TEST1B ADATEST2 ADA TEST3A ADA TEST4 ADA TEST5 ADA TEST6 ADATEST7 ADA TEST1 STY TEST1 FLW 13 File(s) 533504 bytes free


35/156

______________________________________________________________________________________CMU/SEI-89-EM-1 31

Tools Directory Listing

Volume in drive A is DASC

Directory of A:\TOOLS

. .. DASC COM UP_UNIX COM UP_VMS COMDWN_UNIX COM DWN_VMS COM COMPILE DOC INSTALL DOC 9 File(s) 533504 bytes free

The t ools dir ectory includes t he followin g files:

dasc.com A DE C Comma nd La ngua ge (DC L) file tha t is the user interfaceto the DASC system on a VAX VMS computer system.

up_unix.com A UNIX C shell script tha t cha nges the short (8 cha racter) filena mes for a n MS-DOS system t o the long file names used on aUNIX system.

up_vms.com A DE C Comma nd La ngua ge (DC L) file tha t changes the short(8 character) file names for an MS-DOS system to the long filena mes used on a VMS syst em.

dwn_unix.com A UNIX C sh ell script tha t cha nges the long file names used ona UNI X system to the short (8 chara cter) file na mes for a n MS-DOS system.

dwn_vms.com A DE C Comma nd La ngua ge (DC L) file tha t changes the longfile names used on a VMS system to the short (8 character) filena mes for an MS -DOS syst em.

compile.doc A listing of the order in wh ich the 63 source files mus t becompiled.

install.doc Describes how to insta ll the version of DASC prepared by t heIP FW students. It ma kes reference to diskettes used by the

students; those references do not apply to the distributiondiskett es tha t a ccompany this report .

Document Directory Listing

Volume in drive A is DASCDirectory of A:\DOCUMENT

. .. CHNGREQ TXT CMPLAN TXT CODESTDS TXTDETDES TXT DISCRREP TXT DOCSTDS TXT PREDES TXT QAPLAN TXTREQDOC TXT TESTPLAN TXT USERMAN TXT 13 File(s) 533504 bytes free


36/156

DASC DISCREPANCY REPORT Report No.: 1Release No.:

Originator: Position:E-Mail Address: Date:

Problem Description/Requirement Not Met: ____________________________________Du ring execut ion, a n exception is ra ised

________________________________________________________________________in t he procedure ENTERING_BLOCK_STRUCTURE.

________________________________________________________________________

________________________________________________________________________

________________________________________________________________________

Correction Description: _____________________________________________________

________________________________________________________________________

________________________________________________________________________

________________________________________________________________________

________________________________________________________________________

Resource Estimation (Hrs) Documentation Affected:

Modification ________

Testing ________ Source File(s) Affected:Other ________ TOTAL ________

CCB Decision Approved As Is ___ Waived ___ Approved For Analysis ___ Reasons Waived:

=====================================================================CCB Signatures: Date:

Request Closed Date:Configuration Manager/Document Specialist Signature:


37/156



Problem Description/Requirement Not Met: __________________________________The compiler reports that ou tmode

____________________________________________________________________par a meters in tw o procedures a re not given va lues. The errors a re report ed for

____________________________________________________________________procedures CREATE_DICTIONARYand TOKEN_IS_FOUND, both of w hich are

____________________________________________________________________defined in package DICTIONARY_MANAGER.

____________________________________________________________________

Correction Description: _________________________________________________

____________________________________________________________________

____________________________________________________________________

____________________________________________________________________

____________________________________________________________________








38/156



Problem Description/Requirement Not Met: __________________________________During the process of transporting the

____________________________________________________________________DASC s yst em to the MS -DOS /Alsys Ada environment , a ll system files with na mes

____________________________________________________________________exceeding 8 cha ra cters were given modified na mes. U pon execution, the syst em

____________________________________________________________________could not find some files, beca use th ey ha d different na mes.

____________________________________________________________________


____________________________________________________________________

____________________________________________________________________

____________________________________________________________________

____________________________________________________________________








39/156



Problem Description/Requirement Not Met: ____________________________________If t he file input file (na med

________________________________________________________________________COMMANDLI.TXTin t he original version of the syst em) is empty or a ny line in t ha t

________________________________________________________________________file is th e na me of a n onexistent file, several exceptions a re ra ised a nd the D ASC

________________________________________________________________________syst em fa ils to perform properly.

________________________________________________________________________

Correction Description: _____________________________________________________

________________________________________________________________________

________________________________________________________________________

________________________________________________________________________

________________________________________________________________________








40/156



Problem Description/Requirement Not Met: __________________________________The compiler reports unreachable code

____________________________________________________________________in function IS_STATEMENT.

____________________________________________________________________

____________________________________________________________________

____________________________________________________________________


____________________________________________________________________

____________________________________________________________________

____________________________________________________________________

____________________________________________________________________








41/156

DASC CHANGE REQUEST Change Request No.: 1Release No.:


Change Type ___ New Feature ___ Cost Reduction ___ Other (describe)X

Correction Description: _____________________________________________________Spelling errors ha ve been noticed in the fla w a nd st yle

________________________________________________________________________report s generat ed by DASC ; these ar e to be corrected. The errors are:

________________________________________________________________________1. Inconsistant I ndentat ion should be Inconsistent Indenta t ion

________________________________________________________________________2. P RAG MAS an d PRAGMAs should be P RAG MAS

________________________________________________________________________3. Reserve word . . . should be Reserved word .. .

________________________________________________________________________4. upper ca se should be uppercase; low er ca se should be low erca se

________________________________________________________________________

________________________________________________________________________


Modification ________ Testing ________ Source File(s) Affected:

Other ________ TOTAL ________

CCB Decision Approved As Is ___ Waived ___ Approved With Modification ___ Reasons Waived/Description of Modification:

=====================================================================

CCB Signatures: Date:



42/156

DASC CHANGE REQUEST Change Request No.: 2Release No.:


Change Type ___ New Feature ___ Cost Reduction ___ Other (describe)X

Correction Description: _______________________________________________

Documents

Class SWEN 648_SW Maintenance