class swen 648_sw maintenance
TRANSCRIPT
-
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.
-
8/12/2019 Class SWEN 648_SW Maintenance
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.
-
8/12/2019 Class SWEN 648_SW Maintenance
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.14. C ha nge Request 3: U ser In ter fa ce, Version 2 17
4.15. C ha nge Request 4: U ser In ter fa ce, Version 3 17
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
-
8/12/2019 Class SWEN 648_SW Maintenance
4/156
-
8/12/2019 Class SWEN 648_SW Maintenance
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-
-
8/12/2019 Class SWEN 648_SW Maintenance
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).
-
8/12/2019 Class SWEN 648_SW Maintenance
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/12/2019 Class SWEN 648_SW Maintenance
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
-
8/12/2019 Class SWEN 648_SW Maintenance
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.
-
8/12/2019 Class SWEN 648_SW Maintenance
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.
-
8/12/2019 Class SWEN 648_SW Maintenance
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.
-
8/12/2019 Class SWEN 648_SW Maintenance
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.
Information for Instructors
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
-
8/12/2019 Class SWEN 648_SW Maintenance
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.
Information for Instructors
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.
Information for Instructors
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.
-
8/12/2019 Class SWEN 648_SW Maintenance
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.
Information for Instructors
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.
-
8/12/2019 Class SWEN 648_SW Maintenance
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.
Information for Instructors
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:
-
8/12/2019 Class SWEN 648_SW Maintenance
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;
-
8/12/2019 Class SWEN 648_SW Maintenance
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);
-
8/12/2019 Class SWEN 648_SW Maintenance
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.
Information for Instructors
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";
-
8/12/2019 Class SWEN 648_SW Maintenance
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.
Information for Instructors
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 .
Information for Instructors
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;
-
8/12/2019 Class SWEN 648_SW Maintenance
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.
Information for Instructors
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;
-
8/12/2019 Class SWEN 648_SW Maintenance
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
Information for Instructors
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.
Information for Instructors
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 .
-
8/12/2019 Class SWEN 648_SW Maintenance
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).
4.14. Change Request 3: User Interface, Version 2
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.
4.15. Change Request 4: User Interface, Version 3
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.
-
8/12/2019 Class SWEN 648_SW Maintenance
23/156
______________________________________________________________________________________CMU/SEI-89-EM-1 19
Information for Instructors
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.
Information for Instructors
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.
-
8/12/2019 Class SWEN 648_SW Maintenance
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 .
Information for Instructors
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.
-
8/12/2019 Class SWEN 648_SW Maintenance
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.
Information for Instructors
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.
-
8/12/2019 Class SWEN 648_SW Maintenance
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.
-
8/12/2019 Class SWEN 648_SW Maintenance
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
-
8/12/2019 Class SWEN 648_SW Maintenance
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.
-
8/12/2019 Class SWEN 648_SW Maintenance
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].
-
8/12/2019 Class SWEN 648_SW Maintenance
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.
-
8/12/2019 Class SWEN 648_SW Maintenance
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
-
8/12/2019 Class SWEN 648_SW Maintenance
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.
-
8/12/2019 Class SWEN 648_SW Maintenance
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.
-
8/12/2019 Class SWEN 648_SW Maintenance
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
-
8/12/2019 Class SWEN 648_SW Maintenance
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
-
8/12/2019 Class SWEN 648_SW Maintenance
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:
-
8/12/2019 Class SWEN 648_SW Maintenance
37/156
DASC DISCREPANCY REPORT Report No.: 2Release No.:
Originator: Position:E-Mail Address: Date:
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: _________________________________________________
____________________________________________________________________
____________________________________________________________________
____________________________________________________________________
____________________________________________________________________
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:
-
8/12/2019 Class SWEN 648_SW Maintenance
38/156
DASC DISCREPANCY REPORT Report No.: 3Release No.:
Originator: Position:E-Mail Address: Date:
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.
____________________________________________________________________
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:
-
8/12/2019 Class SWEN 648_SW Maintenance
39/156
DASC DISCREPANCY REPORT Report No.: 4Release No.:
Originator: Position:E-Mail Address: Date:
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: _____________________________________________________
________________________________________________________________________
________________________________________________________________________
________________________________________________________________________
________________________________________________________________________
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:
-
8/12/2019 Class SWEN 648_SW Maintenance
40/156
DASC DISCREPANCY REPORT Report No.: 5Release No.:
Originator: Position:E-Mail Address: Date:
Problem Description/Requirement Not Met: __________________________________The compiler reports unreachable code
____________________________________________________________________in function IS_STATEMENT.
____________________________________________________________________
____________________________________________________________________
____________________________________________________________________
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:
-
8/12/2019 Class SWEN 648_SW Maintenance
41/156
DASC CHANGE REQUEST Change Request No.: 1Release No.:
Originator: Position:E-Mail Address: Date:
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
________________________________________________________________________
________________________________________________________________________
Resource Estimation (Hrs) Documentation Affected:
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:
Request Closed Date:Configuration Manager/Document Specialist Signature:
-
8/12/2019 Class SWEN 648_SW Maintenance
42/156
DASC CHANGE REQUEST Change Request No.: 2Release No.:
Originator: Position:E-Mail Address: Date:
Change Type ___ New Feature ___ Cost Reduction ___ Other (describe)X
Correction Description: _______________________________________________