90em003

7/27/2019 90em003

1/173

Educational MaterialsCMU/SEI-90-EM-3

August 1990

Reading Computer Programs:

Instructors Guide and Exercises

Lionel E. Deimel

Software Engineering Curriculum Project

J . Fernando Naveda

Un iversity of Scrant on

Approved for public relea se.

Distribution unlimited.

Software Engineering InstituteCa rnegie Mellon U niversity

Pit tsburgh, Pennsylvania 15213

7/27/2019 90em003

2/173

This document w a s prepared for the

SEI J oin t P rogram Off iceE S D /AVSH a nscom AFB , MA 01731

The ideas a nd findings in t his document should not be construed a s a n

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

technica l informa tion excha nge.

Review and Approval

This document ha s been reviewed a nd is a pproved for publication.

FOR THE COMMANDE R

J OHN S. HERMAN, Capt , USAFSEI J oint P rogram Off ice

This w ork is sponsored by the U .S. D epart ment of Defense.

Copyright 1990 by Ca rnegie Mellon U niversity.

This document is a vaila ble through the Defense Technical In format ion Center. DTIC provides access to and tr an sfer ofscientific and technical information for DoD personnel, DoD contractors and potential contractors, and other U.S.Government a gency personnel and t heir contra ctors. To obta in a copy, please conta ct DTIC directly: Defense TechnicalInforma tion Cent er, Attn: F DRA, Ca meron St at ion, Alexandria , VA 22304-6145.

Copies of this document are a lso ava ilable through the Na tional Technical Informa tion Service. For informa tion onordering, please conta ct NTIS directly: Nat ional Technical Informa tion Service, U.S . Departm ent of Commerce,Spr ingfield, VA 22161.

Use of any tra demarks in this document is not intended in any wa y to infringe on the rights of the tra demark holder.

7/27/2019 90em003

3/173

Table of Contents

1. Introduction 1

1.1. Wha t I s P rogra m Rea ding? 1

1.2. Overview of This Report 2

2. The Importance of Program Reading Skills 5

2.1. G row ing Aw a reness of P rogra m Rea ding I ssues 6

3. How Do People Read Programs? 9

3.1. Wha t I s P rogra m U nderst a nding? 9

3.2. P rogra m Rea ding S t ra t egies 11

4. Readability Factors and Tool Support 15

4.1. Fa ctors Affect ing P rogra m Rea da bilit y 15

4.2. Rea da bilit y a nd S t yle 174.3. Tools a nd Techniq ues 17

5. Teaching Program Reading 21

5.1. Need P rogra m Rea ding B e Ta ught ? 21

5.2. Tea ching S t ra t egies 22

5.3. Some Addit iona l Idea s 26

6. Constructing Reading Exercises, with Examples 29

6.1. E va lua t ing P rogra m Rea ding S kills 29

6.2. E xa mple P rogra m Rea ding Quest ions 32

6.2.1. Know ledge-Level Quest ions 36

6.2.2. Comprehension-Level Quest ions 38

6.2.3. Applica t ion-Level Quest ions 39

6.2.4. Ana lysis-Level Quest ions 41

6.2.5. Synthesis-Level Quest ions 44

6.2.6. E va lua t ion-Level Quest ions 46

Annotated Bibliography 49

Acknowledgements 69

Appendix: Program Source Code 71Diskette Order Form 169

7/27/2019 90em003

4/173

7/27/2019 90em003

5/173

Reading Computer Programs:Instructors Guide and Exercises

Abstract: The ability to read and understand a computer progra m is a crit i-cal skill for the software developer, yet this skill is seldom developed in anysyst emat ic w a y in the educa tion or tra ining of softw a re professionals. Thesematerials discuss the importance of program reading, and review what isknown about reading strategies and other factors affecting comprehension.These ma teria ls a lso include rea ding exercises for a modest Ada program a nddiscuss how educators can structure additional exercises to enhance programreading skills.

1. IntroductionThis report has two main objectives: to convince teachers of future computer profes-

sionals of the importa nce of program rea ding, a nd t o provide sam ple exercises to facil-

ita te the teaching of progra m reading. We w ill review the litera tur e relevant t o pro-

gra m reading, and discuss teaching approaches and techniques. A large part of the

report is devoted to the listing of an Ada program for which we provide reading ex-

ercises tha t fulfill a r a nge of educa tional objectives. The progra m a nd exercise ques-

tions are ava ilable on diskette from the Softwa re Engineering Instit ute (SE I). An order

form for ma chine-read a ble versions of this ma teria l is provided at the end of the report.

Readers a re encoura ged to adapt the ma terials to their own part icular needs.

Although the reading exercises are based on the Ada programming language, it wouldbe a mista ke to view t his as a n Ada r eport . Most of wha t w e will say about progra m

reading is independent of any part icular language, although we make no special at-

tempt t o discuss la ngua ges other t ha n high-level procedura l ones. Ada i san a t t rac t ive

vehicle to illustra te r eading exercises beca use it conta ins good mecha nisms for concur-

rency, informa tion hiding, an d the like. Exercises a re provided to explore these facil-

ities and to explore the Ada la ngua ge genera lly. The reader wh ose student s ar e not

using Ada can nonetheless benefit from the ideas w e present, including our suggestions

for genera ting rea ding exercises from mat erials other th a n those provided here.

1.1. What Is Program Reading?

B y program readin g(or code r ead i ng), w e mean th e process of ta king computer s ource

code and, in some wa y, coming to underst a nd it . We mean t o ma ke no presupposi-

tions about whether or not the code contains internal documentation (comments) or

w hether a ny form of externa l documenta tion (design, structure chart s, etc.) is ava ilable

to the rea der or ca n be easily crea ted.

Presumably, some of what can be said about code reading also applies to at tempts to

understand other documentssoftwa re specifica tions or designs, for exam ple. We will

CMU/SEI-90-EM-3 1

7/27/2019 90em003

6/173

not, however, a tt empt t o genera lize to these other life-cycle products, in pa rt beca use of

their diversity of representa tion. Except w here we note otherw ise, w e mea n for our

remarks to be applied only to the realm of high-level procedural languages, although

much of wh a t w e will say a pplies to code outside this cla ss.

We will ha ve more to say about wh at we mean by progra m understan ding. For now,

it is important to realize that we do not often read programs for what might be intui-

tively described as total understanding. We usually read programs for particular

purposesto determine if they ha ve part icular properties such as correctness, or to dis-

cover how an enhancement can be made with minimal disruption to the programs cur-

rent functiona lity. When we speak of reading a program , we refer to a process tha t

aims to achieve whatever degree of understanding is needed to accomplish our partic-

ular objectives.

1.2. Overview of This Report

In the next chapter, we argue the importance of developing program reading skills

a mong softw a re developers. We also mention educa tional issues associa ted w ith pro-

gra m reading, issues we w ill deal with at greater length in Cha pter 5.

In Chapter 3, How Do People Read Programs?, we discuss theoretical and empirical

research on program reading, and examine proposed models of program comprehen-

sion. We try to a nsw er questions such a s: Wha t does it mea n to underst a nd a

program ? a nd How do program mers ascerta in the mea ning of a progra m? The cha p-

ter provides useful background for the instructor who wants to teach program reading

skills. Some of this mat erial should a lso be sha red with st udents in lectures.

Chapter 4, Readability Factors and Tool Support, discusses factors that affect theease wit h which a progra m ca n be underst ood. Much sty listic a dvice to progra mmers

in the litera ture is implicit ly based on a ssumptions a bout w hat ma kes a progra m read-

a ble. Likewise, observa tions a bout factors tha t ma ke a program rea da ble imply cor-

responding sty le rules. In t his cha pter we look at t he relation of empirical observat ions

to programming sta nda rds. We also discuss tools that can ma ke program reading eas-

ier, now or in the future.

In Teaching Program Reading, Chapter 5, we assert that program reading is a skill

tha t should be ta ught explicitly. We discuss wha t ca n be ta ught a nd how. We a lso look

at other uses of program reading in the classroom, whereby students can develop their

rea ding skills in th e pursuit of other educationa l objectives.

Chapter 6, Constructing Reading Exercises, with Examples, contains a discussion of

how t o construct progra m rea ding exercises. The cha pter a lso conta ins specific ex-

ercises targeted to a variety of educational objectives and based on the concurrent Ada

program listed in t he Appendix.

We have included an annotated bibliography, which contains not only references cited

in the text, but also relat ed litera tur e. We have tried to indica te the significa nce of

each entry a nd suggest how it might be used in teaching. In most ca ses, we ha ve sum-

2 CMU/SEI-90-EM-3

7/27/2019 90em003

7/173

ma rized the content of the entry . These a nnota tions often ela borat e on ideas trea ted

only briefly in the text. The bibliogra phy is by no means complete, but w e believe tha t

interested readers can locat e other rea ding-related papers a nd monogra phs tha t might

be of interest to them by r eading t he references w e have included, man y of w hich them-

selves have excellent bibliographies.

CMU/SEI-90-EM-3 3

7/27/2019 90em003

8/173

4 CMU/SEI-90-EM-3

7/27/2019 90em003

9/173

2. The Importance of Program Reading Skills

The successful progra mmer must ma ster a number of diverse skills. One tha t is often

overlooked is the ability to rea d and underst a nd a program . Reading competence is

most obviously relevant to program maintenance, for which the programmer must gainsufficient understanding of the code to design modifications that extend, adapt, or cor-

rect it , while reta ining its logica l, functiona l, a nd stylistic integrit y. Since, typically,

more than half the resources devoted to a program over its lifetime is expended on

maintenance, and since reading the program can be an important step in the mainte-

nance process, lack of adequate reading skills among maintenance personnel can have

serious finan cia l consequences.

B ut progra m reading ability is a lso import a nt in non-ma intena nce a ctivities. Effective

code verification and code reviews require reviewers to understand and analyze the

code under scrutiny. The expert rea der is a va luable team m ember in such cir-

cumstances, as well as a resource to colleagues when they are having a difficult time

debugging.

Code reading provides an all-too-infrequent opportunity for programmers to share and

learn from one anothers w ork. Code examined in forma l reviews and in progra m

librar ies an d repositories; published program s; a nd code found in professional journa ls

all offer the programmer the chance to deepen his understanding of his craft and im-1prove his skil ls . Learning a new programming language is of ten fac il it a t ed by reading

existing code w ritt en in tha t langua ge by more experienced program mers. St udying

progra ms in this w ay allows the progra mmer to gain a sense of proper idiom a nd style

more quickly and surely than does studying language reference manuals, style guides,

an d coding standa rds.

A programmer who reads programs effectively can increase his code generation effi-ciency. He is better a ble to find an d evalua te code tha t can be reused or ada pted tha n

a re his less program -litera te colleagues. This a bility allows him t o avoid a g ood deal of

coding altogether. When working on a large softw a re system, a program mer needs to

be reminded of the details of code written so long ago that those details are no longer

fresh in his mind. Fa cility in reconstr ucting such informa tion from code, even ones

own, ca n th erefore be a va luable asset .

St udents in a cademic progra ms do get occasional opportunities to pra ctice reading pro-

gra ms. They are presented with code in intr oductory and da ta st ructures textbooks,

a nd possibly in t extbooks used in courses on oth er topics, such as a na lysis a nd design of

algorithms. Students a re sometimes given example programs by their instructors a nd

may have to struggle to make sense of program units writ ten by fellow students onteam projects, such as might be part of an introductory software engineering course.

Rarely, examinations require students to interpret code.

1We will follow the traditional convention of using masculine terms where the personspoken of ma y be either m a le or fema le. No offense to female professiona lswho aredistressingly und errepresented in the w orkplaceis int ended, of course.

CMU/SEI-90-EM-3 5

7/27/2019 90em003

10/173

Nonetheless, it is fair to say that the improvement of program reading skills is vir-

tually unknown as an explicit educational objective among those teaching future soft-

w a re developers. Yet the ava ilable evidence suggests t ha t our current neglect of the

topic cannot be justified by the argument that adequate program reading skills develop

naturally and without special encouragement in students otherwise well prepared toenter professiona l pra ctice.

We advocate that instructors undertake activities designed to teach and improve pro-

gra m reading skills among their students. Although this suggestion is radical a nd

lar gely untr ied, substa ntia l benefits might be ga ined. Not only is there potent ial for

graduating students better able to perform important tasks such as program mainte-

nance, but there is also a realistic hope that students will become better learners in

advanced courses by virtue of their greater ability to understand program examples

tha t illustra te specia lized techniques. Such students should also be better learners on

the job. Cla sses of competent progra m readers can be given exam ina tion questions to

test t heir progra m-w riting skills more reliably by mean s of questions based on progra m

fragments tha t must be read .

No doubt, many educators will object to our suggestion of teaching program reading,

protest ing either tha t educators have no idea how to carry out such a suggestion or t ha t

they ha ve no time to do so. We will tr y to counter these argum ents by enumera ting

techniques that can be used in the classroom, including activities that use program

rea ding incidenta l to achieving unrelat ed educat iona l objectives. We must point out

that, although no one disputes the importance of teaching program writing skills, there

is har dly a consensus a bout the most effective wa y of doing it . Read ing skills seem

equally important, and our lack of educational experience teaching them seems a poor

excuse for continuing t o ignore program read ing in t he cla ssroom.

2.1. Growing Awareness of Program Reading Issues

Program reading seems to be at tract ing increasing at tention, largely because of i ts

pivota l role in ma intena nce. As early a s 1971, how ever, G era ld Weinberg la mented th e

decline in the practice of reading program s brought a bout by t ime-sha ring [Weinberg71].

He w as less concerned with t he role of reading in ma intenance than with its potential

for teaching; progra mmers could learn a good deal from reading t he progra ms of others,

a s well as their ow n. In th e preface to their well-known book, Th e El ement s of Pr o-

grammin g Style, Kernighan and Plauger make a similar point about the educational

value of reading programs [Kernighan74]. Knuth w as so taken with th e benefits of pro-

gra m reading th at he designed a program ming scheme, literat e programming, tha t rec-

ognizes the huma n rea der to be as importa nt a s the mechanical one [Knuth84]. He has

published two programs in this form, each of which is a sizable book [Knuth86a,

Knuth86b]. Da vid Moffat published a more modest collection of progra m reading s in

P ascal for the beginning student [Moffat84] and suggested, with Lionel Deimel, that pro-

gram reading can play a central role in the teaching of programming generally

[Deimel82].

6 CMU/SEI-90-EM-3

7/27/2019 90em003

11/173

Much of the literature on program r eading deals w ith pr ogram compr ehension, which

encompasses both what it means to comprehend a program and the process by which

tha t comprehension is rea ched. Lukey [Lukey81] lists three approaches to studying pro-

gra m comprehensiont he obser vati onal appr oach, the exper iment al appr oach, and the

ar ti f i cial in tell igence approach. Roughly, these approa ches correspond to the stud y ofprogra mmers reading programs t o see wha t t hey do, the study of programmers rea ding

in situat ions where certain factors are fixed and others are allowed to vary in con-

trolled ways, and the production of tools that serve to mechanize or assist in the pro-

gra m comprehension process. P a pers describing each approach have not only increa sed

in number over the years, but also are now more likely to appear in such mainstream

computer journa ls a s Comm uni cati ons of t he ACM.

Of course, observations of what makes a program readable have implications for how

progra ms should be writ ten a nd forma tted. In a ddit ion to a num ber of books advo-

cat ing a certain programming style (e.g., [Kernighan81]), some authors are making more

radical proposals affecting the visual display of programs [Baecker90, Oman90a,

Oman90b], or are looking to environments that support program reading in a more or-ganic wa y [Goldberg87].

We consider it importa nt a nd exciting t ha t both t he Florida/P urdue Softw a re Engineer-

ing Research Center (SERC) [Wilde89] a n d I B M [Corbi89] have undertaken significant

efforts to study program comprehension and to explore tools to assist programmers in

rea ding progra ms effectively . We expect such tools eventu a lly to become commonpla ce,

although they will not obviate the need for programmers to have good program reading

skills of their own in order to use these tools effectively.

CMU/SEI-90-EM-3 7

7/27/2019 90em003

12/173

8 CMU/SEI-90-EM-3

7/27/2019 90em003

13/173

3. How Do People Read Programs?

Wha t do w e know about how people rea d or should rea d progra ms? Severa l writers

ha ve offered advice a bout how w e should go about read ing code. Through experimenta l

and observat ional studies, we have indicat ions of how actual programmers behavewh en trying to understand unfa miliar code. Finally, there have been many a t tempts to

construct models of program understanding, both to explain empirical findings and to

make useful and verifiable inferences about how program reading can be carried out

more effectively. Let us look a t models of program underst a nding or, a s they ar e

usua lly called, program comprehension m odels.

3.1. What Is Program Understanding?

If w e are t o construct a useful theory of progra m rea ding, we requir e a model to help us

explain h ow we come to understa nd a program , as well as w ha t w e can be said to know2wh en we do understand th at progra m. There must be a computer science component

in any such model, of course, but there are also behavioral and psychological compo-

nents. Ma ny researchers in the field of progra m reading ha ve a pproa ched their studies

from a cognit ive psychology or art ificial intelligence point of view . Alth ough this is not

remarka ble, we point it out to alert t he reader tha t t he study of program rea ding, while

importa nt t o softw a re engineering, is not str ictly a n a rea of computer science research.

Let us first look at w ha t w e know w hen we understa nd a progra m. Almost an y pro-

gra mmer could generat e a useful l ist . We understa nd wha t each stat ement means,

how flow of control passes from one statement to another, what algorithms have been

employed, how information is represented and transformed in data structures, which

subprograms invoke other subprogra ms, a nd how the progra m intera cts w ith its envi-ronment. Ruven Brooks ha s described all this informa tion a s a succession of

knowledge domains that bridge between the problem domain and the executing pro-

gram [Brooks78, Brooks82, Brooks83]. A know ledge doma in is a collection of informa tion

a bout objects of some sort a nd rela tionships among t hose objects. (One ma y th ink of

this in the m a thema tical sense of a set of objects, a collection of relat ions, a nd so forth.)

According to Brooks, the knowledge domains include (or may include): the problem

domain; the domain of some mathematical model for the real-world problem; an al-

gorithmic domain of abstract data structures and operat ions; an implementat ion

domain of arrays, assignments, and the like; and a domain of bit pat terns stored and

ma nipulat ed in specific stora ge loca tions with in the computer. (It is easy to ar gue

a bout the bounda ries of these doma ins an d wh ether there a re more or few er of interest.

Certa inly the progra m str ucture domain

which includes objects like procedures, func-t ions, and tasksdeserves mention.) If one really understands a program, according to

this theory, one possesses the knowledge of each of the domains, as well as the ability,

thr ough knowledge of inter-domain r elat ions, to relat e conceptiona lly ad jacent domains

2We use the term program to mean any appropriate piece of code, be it a completeprogram, a subprogram, or even an isolated segment.

CMU/SEI-90-EM-3 9

7/27/2019 90em003

14/173

to one an other. The process of understa nding a program is one of constructing (or

reconstructing) the knowledge domains and relations among them from the code, com-

ments, and wh at ever other documentat ion is a vailable.

Even in the a bsence of theoretical or empirica l underpinnings, B rookss model is intui-

tively appealing. It seems to ca pture succinctly most of w ha t might r easona bly be con-

strued as knowledge about a program, and it suggests part icular ways in which our

knowledge can be incomplete. For exam ple, we may underst a nd a program perfectly

statement-by-statement, yet fail totally to comprehend, on a more abstract level, what

it does an d wh y. B rooks has used his model to ma ke inferences about documenta tion.

Effective documenta tion commun ica tes informa tion not explicitly present in t he source

code itself (i.e., it ad ds to the informa tion ava ilable to the read er). Therefore, lan -

guages like traditional FORTRAN may require more explanation of their code than

languages like Pascal, which allow direct manipulation of higher-level abstractions

[Brooks82].

Another point made by Brooks deserves special mention, namely that the code itself

(i.e., the actual source-language statements) is notthe ult imat e aut hority w ith respect

to program meaning. On one hand, this stat ement is surprising. A progra m designa tes

some computa tion, which ma y be ta ken to be its sema ntics or mean ing. Therefore,

given a well-defined programming language and computing platform, a syntactically

correct progra m definitively specifies wh a t t he progra m does. It is t his point of view, a s

expressed by Kernighan and Plauger in The Elements of Programming Style

[Kernighan74], tha t Br ooks at tempts to counter. Kernighan and P lauger argue tha t a

program and its documentation provide multiple representations that are subject to in-

consistencies and that, therefore, the only reliable documentation of a computer pro-

gra m is the code itself. B rooks ar gues, in effect, tha t such a position ignores the larg er

context in w hich progra ms exist. To begin with, a progra ms function is pa rtly a ma tt er

of the interpretation given the input and output, information perhaps only hinted at inthe code. Fur ther, for purposes such as ma intena nce, explicit sta tement s about as-

sumptions a nd design decisions th a t led to the source code ma y be more importa nt t ha n

the code itself for the programmer trying to understand the program.

Severa l aut hors ha ve proposed models similar t o tha t of Ruven Brooks. The differences

a mong these models seem mostly confined to minor details an d nomenclatu re. In a ny

case, the la yered str ucture of ones knowledge of a program is a common element in a ll

these t heories.

Sh neiderman a nd Ma yer ha ve proposed a synt a ctic/sema ntic model of progra mmer

behavior [Shneiderman79]. The model is intended to a pply to writ ing progra ms, as w ell

as r eading them, modifying them, and learn ing to program. The model assumes tha tsemantic and syntactic knowledge is stored in long-term memory and manipulated in

short-term memory and working memory. P rogra m comprehension, they suggest, is

largely a ma tter of building up a hierarchy of sema ntic knowledge about the program,

with informa tion about w hat the progra m does a t t he top of the hierarchy, and lower-

level informat ion about sta tement s and algorithm s below . The representa tion is in

terms of abstractions (representing the function of groups of statements, for example)

derived from the progra m text. All the menta l machinery of the synta ctic/sema ntic

10 CMU/SEI-90-EM-3

7/27/2019 90em003

15/173

7/27/2019 90em003

16/173

Empirical evidence suggests t ha t t he human program reader is wh at Letovsky calls a n

opportunistic processor, capable of using multiple reading strategies [Letovsky86a].

The basic stra tegies people have w ritt en about, however, ar e top-downa nd bottom-up.

Top-down reading of a program is analogous to the more familiar top-down develop-

ment a pproa ch. One begins by ga ining an underst a nding of the overa ll purpose of the

program, then tries to understand how that function is implemented by component

pieces. In carr ying through this process, the rea der forms hypotheses a bout these

piecesthey may be procedure calls, individual loops, or other fragmentswhich a re

lat er verified or modified thr ough recursive applica tion of this method. Letovsky de-

scribes this approach as building a representation of the specification first and then

w orking dow n to the implementa tion level.

Read ing bott om-up proceeds in the opposite direction. U nderst a nding of sma ll fra g-

ments of code is aggregated into descriptions of larger pieces of the program until the

overa ll progra m function and st ra tegy ha ve been discovered.

It is worth noting here that tw o char acterist ics of a progra m ha ve a dominant influenceon reading approaches tha t m ay be ava ilable: the degree of documentat ion a nd w hether

the program is str uctured. Linger, Mills, and Witt point out t ha t poorly documented

code generally must be read bottom-up, as the lack of documentation can make it

near ly impossible to devise hypotheses about w ha t va rious sections of code accomplish

w ith out exam ining th ose sections of code in deta il. Well-documen ted code ca n usua lly

be read top-down [Linger79].

In explaining how the function of a structured program can be ascertained from an un-

derstanding of its primitive components, Linger, Mills, and Witt also explain why un-

str uctured program s a re difficult to underst a nd. U nst ructured code cannot easily be

resolved into components that interact with one another in a limited number of simple

w a ys. Although the progra m comprehension litera tur e discusses program s ha ving

various levels of documentation, we are aware of virtually no work done on unstruc-

tured program s. Resear chers advise readers to restructure their program s algorith-3mically and then read the newly structured program [Basili82, Linger79]. Tools a re

ava ilable to perform restructuring, at least for some languages, such a s COB OL.

The bottom-up approach to understanding a program is perhaps the easier of the two

bas ic str a tegies to expla in. It is the simpler and, in the sense tha t it ca n be a pplied

with success in the most situa t ions, the most genera l. B asili and Mills show the a ppli-

cation of a bottom-up approach to program understanding in [Basili82]. Their a pproach

is very formal, but the formality is inessentia l to understa nding the basic strat egy. Af-

ter convert ing their program into a structured program , they begin to assign mean ing(function) to each pri me program, each structured unit such as an if.. . then .. . else(see [Linger79]). This a ssignment of meaning ma y be done thr ough direct cognition, or

3Because much unstructured code still exists, we can ask if we should teach our stu-dents how t o deal w ith it . P robably a dvoca ting t he procedure described here is the besta pproa ch. Sur ely unst ructured code can be read , and even ma inta ined, but proceduresfor rea ding and ma intenance are necessarily ad h oc.

12 CMU/SEI-90-EM-3

7/27/2019 90em003

17/173

it ma y require more delibera te an a lysis. Since a st ructured progra m is composed only

of sequenced and nested structured units, the function of larger fragments of the pro-

gram may be discovered by combining the functional descriptions of smaller program

components in sta ndar d wa ys. Ca rrying this process through, one arrives at a func-

tional description for the entire program, as well as additional information collectedalong the wa y. Linger, Mills, an d Witt call this stra tegy stepw i se abstr acti on, and it is

certainly a process programmers carry out all the time, particularly for small segments

of code.

Sh neiderma n describes progra m comprehension as proceeding in a sim ilar w a y, though

he substitut es the langu a ge of psychology for tha t of ma thema tics. He describes the

reader as recognizing the function of groups of statements as chunks and combining

these chunks to explain larger program fragments [Shneiderman79].

In B rookss model, the prima ry a ssimilat ion process proceeds top-down. B rooks

obliquely a cknowledges tha t people do use bott om-up str a tegies, but he dism isses them

as less powerful [Brooks83]. The process B rooks describes is one of repea ted hy pothesis

generat ion and verifica tion. Know ing wha tever he knows about the code, the reader

genera tes hypotheses about w ha t the progra m does and how. He tries to verify these

hypotheses by exam ining the code. Evidence tha t feeds hypothesis genera tion comes

from the program text , program comments, and whatever addit ional documentat ion

ma y be ava ilable. If the reader sees a var iable na med DIST_TBL, for example, hemight conclude tha t it probably stores a t a ble of dista nces betw een locations. He would

then tr y to verify this hypothesis by further examining the code. Hy pothesis gener-

ation begins with what is known about the overall function of the program, which often

by itself causes the reader to expect to see certain features in the programsorts,

ma ster a nd tra nsa ction files, a nd the like. Hy potheses tend to be non-specific a nd

therefore usua lly are not directly verifiable. Inst ead, they ca use subsidiar y hypotheses

to be generated in a hierarchical fashion until a level is reached at which hypothesescan be directly verified or proven false. The reader scans t he code in var ious w a ys

sear ching for clues in the text tha t bear on current hy potheses. In th is sca nning proc-

ess, he looks for beacons, which are typical evidence for certain structures or opera-

tions. Tw o nested loops might be a beacon for a sort , for example. The progra m is

underst ood w hen verified hy potheses ha ve been bound to a ll code in t he program .

Several empirical studies have added to our understanding of what programmers ac-

tua lly do w hen reading program s. Videota ped protocols of professional progra mmers

modifying a program are the basis of papers by Letovsky [Letovsky86a] and Li t tman ,

P into, Letovsky, a nd S olowa y [Littman86]. B oth these papers conta in extensive descrip-

t ions and ana lyses of wha t the subjects did. The data show quite clear ly tha t th ey do

not employ pure top-down or bott om-up stra tegies, but freely mix the tw o. Insigh t int ow hy t his should be so comes from Letovskys paper, in w hich he class ifies qu estions the

subjects posed to thems elves. For exam ple, a how quest ion (S o lets see how it

searches the database.) is top-down in nature; a lower-level implementation is sought

for a goal. A wh y question (It s setting IPTR to zero. Id like to know w hy.) is look-ing in the other direction; a goal is sought for a par t of the implementa tion. Other

questions discussed in the paper a re wha t quest ions (I w a nt t o f ind out w hat f ield 7

is.) and whether questions (Is this subroutine actually deleting a record or is it just

CMU/SEI-90-EM-3 13

7/27/2019 90em003

18/173

putting a delete mar k there, a nd the record is still there?). P rogra mmers a re clearly

seen here enga ged in the sort of activity B rooks describes. When seen in its deta il,

however, the process is not simply chara cterized. Letovsky also describes part icular

techniques program mers us e to genera te hy potheses (he ca lls them conjectures) to a n-

swer their quest ions.

Li t tman, et al ., emphasize a different a spect of read ing stra tegy. They report tha t sub-

jects in t heir st udy used either w ha t t hey call a systemat ic stra tegy or an as-needed

str a tegy. Subjects either tried to completely underst a nd the progra m being modified,

or else they tried to gain just enough knowledge to make the change requested in the

program . This ra ises the question of reading objectives; not a lwa ysperhaps not even

oftendoes the rea der really need to know everyt hing about a program . Ones ap-

proach to rea ding is presum a bly conditioned by ones purpose for rea ding. This paper

provides a w a rning, however. Subjects wh o used the systema tic str a tegy, employing

extensive sym bolic execut ion of the code, successfully m odified th e progra m. Those

who cut corners with an as-needed strategy were unsuccessful at the modification task,

a s they fa iled to detect critical intera ctions a mong progra m components . This is a dis-tressing outcome, as t ruly large progra ms ma y not be amena ble to total understa nding.

Although the Letovsky and Lit tman papers suggest that actual comprehension strat-4egies are eclect ic, they do not cast doubt on the layered mental models discussed in the

last section. A similar messa ge ca n be inferred from [Pennington87]. P ennington found

that readers who focus on both the problem domain and the program domain, as op-

posed to focusing on one or the other, are more successful, a result one might reason-

ably expect from, say Brookss model of comprehension.

Severa l of the references conta in brief but useful reviews of at least par t of the program

comprehension litera tur e. See, for example, [Baecker90], [Corbi89], [Crosby90], and

[Wilde90].

4Students should understand both top-down and bottom-up strategies, and should befam iliar w ith descriptions of the eclectic processing tha t is apparent ly typica l. Know -ing about alternative strategies should help students select appropriate ones in partic-ular situat ions.

14 CMU/SEI-90-EM-3

7/27/2019 90em003

19/173

4. Readability Factors and Tool Support

In t his cha pter, we further examine the pra gma tics of reading progra ms. Wha t a re the

factorseither interna l or externa l to the programtha t a ffect how difficult a program

is to read? How does the style with w hich a program is w rit ten a ffect i ts reada bility ,and how can observat ions about readability be translated into useful coding style

guidelines? We will a lso examine reading st ra tegies in more deta il and see how exist-

ing and future softwa re tools can aid t he program reader.

There is inadequa te space here to trea t t hese topics thoroughly. There ar e, how ever,

few actual facts to cite. Our knowledge is tant alizing and fragmenta ry, with most of

the obviously interesting questions having ambiguous answers (how long should a pro-

cedure be?) or none at a ll (w ha t is the most reada ble programm ing langu a ge?). Yet

softwa re development is a pra ctica l enterprise, not a t heoretical one; w e ca nnot w a it for

the a nsw ers. We must look for credible insights w herever they ar e to be found, and5forge ah ead.

4.1. Factors Affecting Program Readability

The study of program comprehension naturally leads us to the question of what makes

a progra m reada ble. We do not have a complete theory tha t a llow s us to predict th e

reada bility of a progra m, but it is not difficult to offer a l ist of para meters tha t m ight be

importa nt. Some of these factors have been investiga ted systema tically, some not.

(The recently published bibliography by Thomas and Oman contains references to

many of the factors discussed below [Thomas90].) We ma y cla ssify these para meters

into th e follow ing cat egories:

1. Reader char acterist ics.

2. Intr insic factors.

3. Representa t ional fa ctors.

4. Typographic factors.

5. Environmenta l factors.

It should be clear from the previous chapter that the reader has a great effect on how

successfully a part icular program is rea d. Comprehension models suggest tha t the

readers knowledgeof programming, of the programming language, and of the appli-

cation domainas well as his reading strategy are important variables [Brooks83]. The

rea ding stra tegy is sometimes a function of the program mers purpose in reading . For

example, the as-needed strategy in response to limited goals, described by Littman, etal ., in [Littman86], led directly to comprehen sion errors . In [Letovsky86b], Letovsky and

Soloway describe how the unwillingness of readers to search for information not imme-

5We did this in th e ca se of structured program ming, for insta nce. Although str ucturedprograms have certain logical advantages over non-structured ones, we have neverprovedth a t str uctured progra mming is superior. Even th e hypothesis is ill-defined.

CMU/SEI-90-EM-3 15

7/27/2019 90em003

20/173

diately near the code they are examining predictably leads to comprehension errors.

P erhaps beca use program rea ding skills have not t ra dit iona lly been ta ught , more than

one study ha ve included sta tement s like the follow ing from [Littman86]:

Finally, we note that there was virtually no relat ionship between years of

professional programming experience and either successfully performing theenha ncement t a sk or the program mers choice of study st ra tegy.

Perhaps this is another manifestation of the well-known disparity in efficiency among

professiona l progra mmers.

It is reasonable to suppose that programs possess a greater or lesser degree of intrinsic

complexity, wh ich affects their rea da bility. It is difficult to say how to mea sure this

complexity, a nd, for th is reason, the field of softw a re metrics is controversial. Sur ely a

hello, world program is less intrinsically complex than the average program to com-

pute B essel functions. Moreover, concurrent or rea l-time program s a re probably more

complex than comparable programs without these characteristics, and very large pro-

gra ms ar e difficult to rea d simply by virtue of their size. B rooks notes tha t there are

abstruse problems that have simple programs as their solutions; the nature of the prob-

lem may still make these programs difficult to comprehend [Brooks83]. Shneiderman

discusses logical, structural, and psychological complexity of programs and their rela-

tion to comprehensibility in [Shneiderman80].

The term representa tional factors is delibera tely broa d. It is ea sy to subdivide,

though it can be difficult t o make clear dist inctions a mong the resulting cat egories. We

mean t o include such para meters as the progra mming langua ge, the natur e and inclu-

sion of comments, the architectural structure of the program, the choice of identifiers,

and other choices that need to be made to generate the logicalprogram, while exclud-

ing th ose choices involved with the rela tive placement of program chara cters, which w e

put under typographic factors. Many of these factors are discussed in [Shneiderman80].

Brooks [Brooks83] makes some interesting remarks about documentation, which apply

to interna l comments. He suggests tha t :

Different kinds of documentation are helpful at different stages of com-prehension. In t he early sta ges, high-level progra m descriptions are help-ful, wherea s in la ter st a ges, low er-level informa tion is more useful.

Different la ngua ges need different kinds of document a tion.

Too much documenta tion can obscure a s much a s it can illuminat e.

Typographic factors include the use of upper- and lowercase, fonts, color, and white

space. We mea n to distinguish betw een the logica l progra m an d the representa tion of

it presented to the user. This allows us t o include in this ca tegory rear ra ngements ofthe code such as that effected by literate programming systems [Knuth84]. Interest ing

studies ha ve been ma de concerning typogra phic factors. One of these wa s done by

Miara, Musselman, Navarro, and Shneiderman [Miara83]. In this ca refully done study ,

the authors concluded that indentation to show structure does enhance program

readability, though it is possible to have either too little or too much indentation.

Other studies can be found in the bibliography of this document, in [Shneiderman80], or

in the Thomas a nd Oma n bibliography [Thomas90].

16 CMU/SEI-90-EM-3

7/27/2019 90em003

21/173

Our term environmenta l factors is also somew ha t of a cat ch-a ll. We mean to include

both the physical an d the logica l environment in which reading ta kes place. One may

place room temperature in this category for completeness, but we have in mind partic-

ular ly fa ctors, such a s: th e medium of the program (paper, CR T monitor); externa l doc-

umenta tion; a nd softw a re tools, like editors and compilers. Int erestingly, in this a ge ofhigh-definition workstation monitors, there are many circumstances in which program-

mers still prefer using paper listings, and presumably are more efficient workers for

doing so [Oman90a].

4.2. Readability and Style

A good deal has been written, much of it atheoretical, about programming style, a term

denoting a n a rra y of softwa re-w riting pra ctices involving choice of identifiers, effective

use of la ngua ge featu res, commenting conventions, indenta tion, use of w hite spa ce, use

of case a nd font , a nd the like. To the degree that we learn a bout w hat ma kes a pro-

gra m rea dable, we should be able to turn this knowledge around a nd ma ke it into pro-gra mming style guidelines tha t should produce more rea da ble program s. Inst ructors

who want to teach program reading should be sure their students make this connec-

tion. The reader is directed to [Baecker90], [Oman90b], [Shneiderman80], and [Thomas90].

4.3. Tools and Techniques

As we ha ve seen, actua l progra m read ing beha vior is complex. Although we cannot

offer a general plan for reading programs, we can provide hints, suggest simple tools

tha t can be used, and cat ch a glimpse of aut oma ted support tha t might be available in

the future.

We begin with a list of ideas for program reading, designed more for suggesting what

sort of a dvice we ca n offer our student s tha n a s a complete ba g of tricks. Read ers ca n

no doubt a dd their own entries to our list :

1. B e aw ar e tha t code and comments (or other documentat ion) ma y nota gree. The code ma y be correct a nd th e comments w rong, or t he reverse.B oth ma y be wrong. (The code ma y not accomplish wh a t it is supposed todo, a nd th e comments ma y describe neither w ha t should be done nor wha tis done.)

2. Use indentat ion to help understa nd structure. However, incorrect inden-tation (more likely to come from a human than a compiler orprettyprinter) may be misleading.

3. Try to build a model of the st yle conventions used in the progra m. If, forexample, a consistent scheme has been used for identifiers, this knowl-edge can be used to help understand the meaning of newly encounteredidentif iers. I t is important t o read the progra m with t he programmersconventions, rather than your own, in mind.

CMU/SEI-90-EM-3 17

7/27/2019 90em003

22/173

4. B e w ar y of a ppar ently a nalogous functions performed in n on-ana logousw a ys. Arbitra ry or stylistic differences may simply indica te progra mmerinconsistency, but they may also signal modified code (a maintainer withdifferent ha bits ha s modified t he code) or code whose functions a re not a sana logous as they might at f irst appear .

5. Consider the possibility that the progra mmer did not know wh at he wa sdoing.

6. Wa tch out for code w ritt en to overcome compiler or computer limita tionsor code conta ining a pparently magicnumbers.

7. Wa tch out for use of nonst a nda rd lang ua ge feat ures. (Some compilers, forexample, initialize var iables th a t other compilers do not.)

8. Use stepwise abstr act ion.

9. Odd-looking ar ithm etic operat ions ma y be required to maint a in accura cy.Consider possible roundoff implications.

10. B eca use cha nges to the code often intr oduce errors an d inconsistencies,look for evidence of cha nges. Look for cha nge logs or comm ent s aboutchanges imbedded in comment s. St ylistic differences can indica techanges by a progra mmer other tha n the aut hor. If multiple versions of aprogram exist, using a tool to find changes (e.g., UNIX diff) ca n be h elp-ful.

11. If, a fter a good deal of study, a piece of code is making n o sense, aska nother progra mmer to look a t it . Consider expla ining to him wha t youthink you doknow.

12. Sea rch for informa tion, par ticularly in documenta tion, tha t relat es objects

in different knowledge domains, for example, comments that associatevar iables w ith problem-domain objects.

13. B e wa ry of objects th a t ha ve the same identifier but different scopes.Reasoning about the wrong objects can be frustrating.

14. B e wa ry of objects ha ving nearlythe same names, part icularly thosew hose identifiers differ by a single cha ra cter.

15. P ar t icular code may be an a rt ifact tha t no longer serves a function.

16. B e sure you make no inessential a ssumptions w hen reasoning about con-current progra ms.

17. B e alert for var iables that serve more tha n one function or tha t a re usedinconsistently, as they can mislead the rea der.

18. The effect of appar ent bugs in th e progra m can be undone by an inversebug somewh ere else.

19. U se symbolic execution t o determine function.

20. U se code substit ution to verify or refine hypotheses. Subst itut e code forwhat you th inkis being performed into the program, and examine howyour code differs from w ha t code is actua lly there.

18 CMU/SEI-90-EM-3

7/27/2019 90em003

23/173

21. Tra cing code with test da ta , wh ether by ha nd or using a symbolic debug-ger, will not by itself tell you wha t function the code performs. How ever,it can help suggest some hypotheses a nd eliminat e others.

22. B e alert for li terals tha t a re conceptua lly dist inct but t ha t ha ppen to have

the sa me values. (The trouble usua lly begins wh en one tries to modifysuch code.)

23. In langua ges tha t permit opera tor overloading, be sure the operator youthink you ha ve is really the one you do have.

24. B e willing to aba ndon hypotheses for w hich there is insufficient evidence.

25. U se program sl i cing[Weiser81]. Throw out pa rt s of the program irrelevantto the particular function or state of the program of interest, in order tostudy the progra m.

26. Use a n editor or browser to tra verse the code. Editors tha t support mult i-ple w indows can show severa l pa rt s of the program a t once.

27. File sear ch tools such a s U NIX grep can be used to find identifiers thatma y be in one of several files.

28. In the a bsence of tools like a cross-reference generat or, such unlikely t oolsas spelling checkers can be useful for listing the identifiers used in theprogram.

29. Tra ditional debugging techniques ca n be used to readcode. The a ddi ti onof print sta tements , for exam ple, ca n be useful in verifying hypotheses.

30. Read progra ms w ith a cross-reference listing, stru cture cha rt, or similarsumma ries of program informat ion close a t ha nd. It is sometimes useful

to genera te such chart s by ha nd if they cannot be obta ined a utomat ically.

Although progra mmers commonly use compilers, editors, a nd prett yprinters, in the fu-

ture, more sophisticated tools to assist with program reading may become available.

Prototype tools for viewing programs in different ways and exposing dependencies

among program components are described in [Cleveland89], [Pazel89], and [Wilde89]. I t

ha s even been suggested tha t st epw ise abstra ct ion ma y be a utomat ed to some degree.

Wilde [Wilde90] discusses kinds of program dependencies that may be of interest to the

progra m reader, a s w ell as reading tools.

CMU/SEI-90-EM-3 19

7/27/2019 90em003

24/173

20 CMU/SEI-90-EM-3

7/27/2019 90em003

25/173

5. Teaching Program Reading

In this chapter, we consider a ct ivit ies th at educat ors can use to teach students how to

rea d progra ms, an d help them t o improve their program r eading skills. We also con-

sider how program reading can be used in situations where teaching reading skills isnot t he principa l educat ional objective.

5.1. Need Program Reading Be Taught?

We argued in Cha pter 2 that progra m reading skills are importa nt t o the softwa re pro-

fessiona l. B ut need we, as educat ors, work consciously to develop these skills among

students, or ma y w e assume tha t rea ding skills are somehow picked up along the wa y

to gaining progra m w riting competence?

Although it is no doubt true that some students seem to develop reading skills effort-

lessly

as effortlessly and mysteriously as they achieve writing skills

we believe thatrea ding skills, in general, require cultivat ion. We have four reasons for this belief:

1. The nat ure of reading a nd w rit ing skills.

2. The ty pica l experiences of student s.

3. Em pirica l evidence from published studies.

4. Our own classroom observat ions.

It should be obvious from our ea rlier discussion of comprehension st udies tha t t he a cti-

vit ies one engages in when reading a programrecognizing, hy pothesizing, verifying,

abst rac t ingare different from the tasks normally associated with writ ing programs.

There is no pa rt icular rea son to expect th ese tw o sets of skills to be equa lly developed.

St udents a re probably called upon t o read progra ms less frequently t ha n t hey will be as

softwa re developers. Not only do they w rite progra ms more often tha n they ana lyze

them, but also the programs they do write are seldom criticized in detail for style and

document a tion. As a result, student progra mmers develop persona l sty les tha t seem

quite natural and correct, but which can be counterproductive when students are con-

fronted w ith code wr itten by someone else who is equally individua listic.

Empirical studies show that experienced programmers tend to be better program

readers tha n novices are. Yet the studies also consistently show t hat reading stra t-

egies employed by experienced programmers are diverse, and usually do not correlate

in an y obvious wa y w ith experience [Crosby90, Littman86, Pennington87]. E xperienced pro-

grammers often adopt disastrous reading strategies [Littman86, Pennington87]. Presum-

ably, education can improve such performance, particularly because certain com-

prehension fa ilures a re systema tic and, a lthough t hey ma y not be tota lly preventable,

perha ps we can a rm students with defenses against t hem. (See [Letovsky86b].)

Our observations of student behavior suggest that students do not particularly like to

rea d progra ms, possibly because d oing s o is difficult, possibly beca use it seems less cre-

at ive or sa t isfying tha n w rit ing code, certainly because st udents fail to gra sp its impor-

CMU/SEI-90-EM-3 21

7/27/2019 90em003

26/173

ta nce. In a ny case, students often skim program examples in textbooks, rather t han

study th em. Most student s devote even less at tent ion to sa mple programs distr ibuted

by teachers an d often perform quite poorly on examina tion reading questions. (See

[Deimel85c] for a simple example of this phenomenon.)

5.2. Teaching Strategies

P rogra m rea ding is a complex, poorly understood cognitive activity. This surely ma kes

it difficult to tea ch, but not, we think, impossible. In th is section, we suggest wh a t w e

believe to be useful tea ching str a tegies for program rea ding. Although our rema rks ar e

meant to apply mostly to undergradua te educat ion, w here we believe progra m rea ding

should first be taught , graduate educators and continuing education instructors also

should be a ble find idea s here tha t th ey ca n use.

It is not our intent ion t o presume th a t progra m rea ding should become the subject of a

par ticular course. Inst ead, we believe tha t progra m reading should be discussed andpra cticed thr oughout the curriculum. B eca use rea ding progra ms is a skill, like w riting

program s, its ma stery r equires practice over a n extended period.

A strategy designed to make students better program readers should have the following

components:

1. Motivat ion: St udents need to know tha t reading skills ar e importa nt .

2. Theory: Students can be ta ught wha t is known a bout program com-prehension and about part icular r eading stra tegies a nd t echniques.

3. Demonstr a tion: Teachers should not only lectur e a bout reading tech-niques, but should also find opportunities to model reading behavior for

their classes.4. P ra ctice: St udents must be given opportu nities to exercise program rea d-

ing skills.

5. Reinforcement: Students must be encouraged, by feedback and gra ding,to use and improve their reading s kills.

We need not sa y much about the first t w o components . P revious cha pters ha ve dea lt

with the importance of reading skills, our knowledge of program comprehension, and

rea ding stra tegies a nd techniqu es. This mat erial ca n be delivered thr ough lectur es,

ha ndouts, assigned readings, and offhand remarks in class. I t is not necessary to

spend a lot of class time on these topics, but it should be clear that the instructor con-

siders them importa nt. We believe tha t t eaching about comprehension models, if only

informally, is important early on because it helps students formulate what it is theyneed to know about a particular program, as well as the kind of knowledge they should

be acquiring about programs generally.

Somehow, hearing about how to do something is less compelling than actually seeing

the thing done. A teacher can demonstra te progra m reading by handing out a program

to students and reading it himself from overhead slides, demonstrat ing what he does

by thinking aloud. Since the skill he wa nts t o demonstrat e is program reading, not

a cting, the program used should be credibly unfamilia r. A va ria tion is to videota pe

someone reading a program in this ma nner a nd show t he videota pe in cla ss.

22 CMU/SEI-90-EM-3

7/27/2019 90em003

27/173

Student assignments are a good source of programs with which to demonstrate read-

ing. A program from a newly collected a ssignment or one from a previous term can ,

a fter the progra mmers na me is removed, make excellent reading ma tt er for a class. As

a bonus, the teacher can give valuable feedback to the class concerning stylistic prob-

lems likely to be especia lly mean ingful to the student s. This can be an importa nt op-portunity, a s t ime seldom permits giving such feedback with a ny regular ity. B oth

good an d bad program s ca n serve a s examples. This will help student s develop

judgement a nd ta ste. Teaching a ssistant s or graders can sometimes sort t hrough pro-

grams to find suitable examples.

Another possible source of programs to read is system utilities, such as those available

under UNI X. These programs can ma ke good reading mat erial, in par t beca use stu-

dents seem to like looking behind the veil and demystifying familiar programs usually

rega rded as primit ives. The progra m in the Appendix is provided for read ing, and t he

SE I ha s other source code ava ilable as w ell. Of course, the choice of reading ma teria l

must be geared to the maturity of the students and the topics being covered in the

course.

Read ing progra ms in cla ss offers a n interesting alt erna tive to conventiona l lectur es. In

adva nced courses, in w hich students m ay be assumed to have a t least modest program-

ming skills, there is often little reason to develop a program on the blackboard to

demonstra te, say, a new a lgorithm. Instea d, the teacher can simply present a program ,

an d then a nalyze it as w ould a professional programmer trying t o understa nd a ny un-

fam iliar code. This procedure has th e follow ing adva nta ges:

It can save valua ble class t ime.

It demonstrates reading skills and reinforces their importance.

It stresses the analysis, ra ther than synthesis, of programs (which is often

the point of the lectur e any w a y). Since this can be done with code directly out of the textbook, it sends the

messa ge tha t you, too, can ma ke sense out of textbook examples.

It relieves the instructor of the need to demonstrate his superiority byw orking out t he program before the class off the top of his hea d.

There are ma ny w ay s to give students pra ct ice reading progra ms, an essentia l part of

improving their skills. Ma ny instr uctors regula rly distribut e their ow n versions of pro-

gra m solutions to their cla sses after a n assign ment is due. These versions ar e usua lly

intended to serve as models for program writ ing, rather than as material for reading

pra ctice. In principle, student s should rea d these solutions and lear n from them, per-

haps finding better ways of performing operations they found troublesome when they

w ere w riting their ow n progra ms. Experience tells us, however, tha t students often

simply file these programs away somewhere, never to be used, except possibly as

ta blecloths for la te-night pizza. More incentive for reading is generally required. Here

a re possible wa ys of providing such incentive:

Have students correct errors in their own programs after they arereturn ed. Suggest th ey rea d the model program for ideas. This tactic ben-efits some students more tha n it does others. St udents w ho ha ve no errorsto correct ha ve no specia l incentive t o look at the h a ndout.

CMU/SEI-90-EM-3 23

7/27/2019 90em003

28/173

Allow students a few da ys to study t he sample program a nd resubmit theirown, thus a llow ing them to improve their gra des on the assignm ent. This,too, benefits stu dents unequ a lly, how ever.

Ha ve student s add or remove functiona lity from th e model program . They

will a lready understand the applicat ion, and much of their efforts will bedevoted to decoding th e deta ils of the model progra m. In fa ct, the modelneed not even be correct; students can be asked to find and remove a bug.Of course, if this is done outside of class, there is no way to prevent stu-dents from copying solutions from one an other.

Ha ve students a nswer questions about th e sample program . Although gen-eral questions (e.g., Write an essay explaining how this program performsits function.) can work, more limited and specific questions may be moreeffective a t focusing st udents at tent ion.

Each of these strategies forces students to approach the program with particular objec-

t ives in mind. A related idea is to have students exchan ge programs a nd a nswer spe-

cific questions about t hem or evalua te the program s aga inst specific criteria. This pro-vides both reading practice and feedback on programming style and readability.

Read ing exercises need not be a ssociat ed with progra mming a ssignment s, of course. At

an y t ime, the teacher can ha nd out a progra m list ing or ma ke available progra m files.

This should be done in conjunction with a specific exercise or set of questions the stu-

dents are a sked to complete. Ha ving students a nswer questions about program s is an

excellent way to teach them programming techniques and increase their sophistication

in thinking a bout program s. In fa ct, it can be a m uch more effective teaching method

tha n classroom lecture, as the students become act ive part icipants ra ther t ha n passive

listeners.

Asking students to write essays about programs also provides an opportunity for stu-

dents to sha rpen th eir technica l w riting skills. (See the SE I curriculum module

Techni cal Wr it in g for Softwar e Engineer s[Levine90] for other suggestions to improve

students writ ing.)

It is not necessary tha t students w rite forma l essays. Questions requiring brief but

non-obvious answers can be quite effective in giving program reading practice and

teaching what ever it is the instructor wa nts students to learn a bout progra mming. In

fact, students should get experience handling narrow questions before being asked to

deal w ith complex, open-ended ones. The lat ter ca tegory offers a tt ra ctive possibilities,

however. Students can be asked to compa re alterna t ive programs for the same ta sk, or

to evalua te a proposeda nd possibly problemat ica lmodification to a program .

It is possible even to ha ve a little fun w ith progra ms distr ibuted to the class. Try con-

ducting a scavenger hunt w ith a progra m. Ask students to find as ma ny odd features

not bugsin a progra m as they ca n. Such fea tur es can include peculiar identifiers,

unreachable sta tements, useless assignment sta tements, and so forth. P rizes can be

offered to winners w ho find most oddities. B esides a dding interest to the class , this

a ctivity emphasizes tha t even working progra ms a re not necessar ily perfect ones.

24 CMU/SEI-90-EM-3

7/27/2019 90em003

29/173

One of the authors has even offered a monetary bounty on any errors students could

findeven typogra phica l onesin progra ms he distributed. This never proved costly,

but perhaps the aut hor wa s just lucky.

Other act ivit ies that might be tried with programs distributed to students include in-

class code reviews and class discussions of programs students have been asked to

study . Of course, code review s should be part of a ny t eam project.

One of the a uthors regularly uses a type of a ssignment tha t combines program r eading

a nd progra m wr iting exercises. St udents a re given files for an incomplete program ,

w hich they a re asked to finish. The progra m ma y include complete but undocumented

procedures, procedures specified only by comment s, and s o forth. St udents mu st rea d

a nd underst a nd w ha t t hey ha ve been given in order to complete the code a nd documen-

ta t ion .

Do not overlook the possibility of giving quizzes or examinations based on programs

student s ha ve been asked to read outside of class . St udents ma y be less effective pre-

paring to answ er unknown questions tha n ones given them in a dvance, however. Onthe other ha nd, this situa t ion is rea list ic, as ma intenance programmers a re often given

time to familiarize themselves with programs they are to maintain, even though they

cannot know w ha t, exactly, they w ill be ca lled upon to do w ith t hem.

P erhaps a more at tr act ive alternat ive for quizzes and examina tions is the idea of using

rea ding questions tha t do not depend on code studied in adva nce. Read ing questions

can be used to test r eading skills, as w ell as program w rit ing skills, or a t least knowl-

edge of progra mm ing techniq ues. (There is reason to believe th ere is some correla tion

between reading and writing skills. Experienced programmers, for example, seem to

perform bett er in experiments involving progra m comprehension. See, for exam ple,

[Crosby90].)

Now we come to the mat ter of reinforcement. St udents a re usually willing to spend

time learning a subject or performing a task only if there is some sort of tangible

rew a rd involved, usually in the form of a gra de. This is a fa ct of academic life, a nd w e

can only accept it a nd use it to our adva nta ge as educat ors. St udents gra des must

depend in part on reading activities if we are serious about imparting reading skills.

Most of the act ivit ies we ha ve mentioned can be graded in a st ra ightforw ar d wa y; they

should indeed ha ve gra des a ssociat ed w ith them. After a time, students w ill come to

recognize improvement in their reading skills and their understanding of programming

generally, a nd w ill, one hopes, enga ge in reading a ctivities more enth usia stically.

Because becoming a good program reader is part ly a matter of learning how to think

about programs, instructors should explain what answers they were looking for in re-

sponse to reading questions. Review ing exercises in class can be a helpful wa y to give

feedback, though students sometimes need personal comments as to why their answers

w ere not correct.

Reinforcement for the idea that reading is important can also come from the use of

program ming style guidelines. If reading progra ms is import a nt, so is w riting more

rea da ble programs . Oma n and Cook w a rn ag a inst specific guidelines, a nd recommend

CMU/SEI-90-EM-3 25

7/27/2019 90em003

30/173

teaching language-independent principles [Oman90b]. Teachers ha ve to decide how

much stylistic freedom to allow t heir students, however. In a ny case, style guidelines

should be justified in terms of their implications for reada bility. St udents can usua lly

be convinced of the utility of reasonable, well-thought-out conventions, even if the con-

ventions are not perfect. U pperclass stu dents probably should be given more leewa y toexperiment with programming style, though they should be held accountable for their

choices.

We are a wa re tha t m ost of the techniques suggested in this chapter require substa ntia l

w ork by the instructor. Writing program s for student s to rea d, and devising follow -up

projects, is not a simple mat ter. B eca use the benefits can be substa ntia l, however, it

may be worthwhile to establish a department-wide plan to create reusable code and

program repositories where instructors can get (and place) software available for stu-

dent r eading exercises.

In t he next cha pter, we discuss const ruction of progra m rea ding questions. We show

tha t a great dea l of variety is possible and t hat quest ions need not be trivial . We also

offer a fra mew ork helpful for genera ting good progra m rea ding questions.

5.3. Some Additional Ideas

We want to mention a few ideas related to program reading that may be helpful to

educa tors, part icular ly those willing to experiment a bit w ith th eir courses.

We mentioned earlier the suggestion by Deimel and Moffat to restructure the intro-

ductory progra mming course by placing a heavy empha sis on reading . They recom-

mend in [Deimel82] tha t a four-phase a pproa ch be used, in wh ich student s:

1. Use programs.

2. Read programs.

3. Modify progra ms.

4. Write programs.

The first phase introduces students to the kind of products they will later be asked to

create. It helps th em to develop ideas about wh a t ma kes softwa re desira ble to users,

independent of any underst a nding of how m uch work might be necessar y on the part of

developers to a chieve an a ppropriat e level of qua lity. In t he second pha se, stud ents

begin to learn a program ming lan gua ge. One hopes they develop intu ition about how

code should look, so tha t t hey ma ke few er silly composition mista kes la ter on. One

also hopes they begin to see intelligent style conventions and internal comments in apositive lighta s aids to comprehension, ra ther th a n as obnoxious requirements. The

third phase lets students try their wings a bit and serves to emphasize the importa nce

of ma inta ining softw ar e. Finally, students begin writ ing progra ms independently.

The Deimel/Moffat a pproa ch has a decided softw a re engineering sla nt t o it , a nd it m a y

be an a t tr act ive stra tegy to try in undergra duat e programs tha t ha ve a serious commit-

ment to softw a re engineering. No thoroughgoing a tt empt to implement th is approa ch

wh ich w ould require a substant ial body of materia lsis known to the aut hors, how-

ever.

26 CMU/SEI-90-EM-3

7/27/2019 90em003

31/173

Although learning ones first programming language through program reading is some-

thing of an offbeat idea, program mers commonly learn a substant ial a mount a bout sec-

ond and third langua ges by reading progra ms w rit ten in those langua ges. This idea

suggests a number of educational possibilities, including ways to make language sur-

vey courses more meaningful. P roject courses often require student s to use a la ngua gewith which they are unfam iliar . P roviding students, in addit ion to the usual resources,

with sample programs in that language and meaningful reading questions, such as

those provided in Cha pter 6, ma y ease the tr a nsition into use of the new la ngua ge.

Finally, we suggest that encouraging students to do a seriousread of their programs

aft er they are finished can ha ve a sa lutar y effect on their work. Code reviews w ork,

after all, because someone actually looksat the code, even if it appears to be running

sa tisfa ctorily. Ca refully and objectively reading ones progra m, even with out the bene-

fit of other review ers, often uncovers previously unrecognized flaw s. St udents sen-

sitized to the importance of program readability can also improve the readability of

their own program s in this wa y. This is especia lly true with r espect to interna l com-

ments. Knowledge of wh at the reader typically wa nts a nd needs to know, a long with adetached assessment of whether or not the code succeeds at communicating that infor-

mation, can lead to programs that are much better documented than they otherwise

would be. Teachers skeptical t ha t students w ill read th eir own progra ms ma y w ish to

provide opportunities for st udents to review one an others code.

We are at least a l i t t le embarrassed for our profession in suggesting that students

should read w ha t they w rite. No doubt an Eng lish composition tea cher would find it

unthinkable tha t a student should submit a theme with out having read it . B ut pro-

gra ms seem to be different. Whereas a theme ca nnot be evalua ted except by rea ding it ,

a progra m can be executed. And stu dents seem disinclined to a rgue wit h th e success of

a properly running program . We should encourage th em to beha ve otherw ise.

CMU/SEI-90-EM-3 27

7/27/2019 90em003

32/173

28 CMU/SEI-90-EM-3

7/27/2019 90em003

33/173

6. Constructing Reading Exercises, with Examples

To teach program reading, it is essential to construct exercises that require students to

an swer questions about progra ms. In t his chapter, we offer advice about framing indi-

vidual q uestions and a ssembling groups of questions.

Our notion of a progra m rea ding comprehension question is broa d. If a q uestion or

exercise requires understanding source code to answer it , that question fits our defini-

tion. In th is sense, for example, a progra m ma intena nce exercise is a reading q uestion.

Program reading comprehension questions test reading ability and provide reading

pra ctice, w hich presuma bly builds reading skills. Questions must be aboutsomething,

however, so that they necessarily also test for other skills and knowledge, a major

rea son to like rea ding questions, a ll other considera tions aside. Ra ther th a n compli-

cate matters unduly, we will generally speak of measuring program comprehension, ig-

noring a ny other objectives a question might a chieve.

In Section 6.2, we list a number of questions based on the program in the Appendix.These questions are intended to be usable as they are, as well as to be suggestive of

others that might be created by teachers, either for the program we have provided or

for for other softw a re.

6.1. Evaluating Program Reading Skills

A major problem of teaching program reading is that of evaluating students under-

sta nding of the mat erial . P rogram reading skills cann ot be measured direct ly because

t he productof program underst a nding is in student s head s. As we shall see, however,

a gr eat va riety of question types is ava ilable to us. G ood comprehension questions ca n

be constructed w ith just a little effort.

Much of the remainder of this chapter is based on [Deimel84], [Deimel85a], and

[Deimel85c]. The reader should consult th ese papers for add itional deta ils and sugges-

tions.

In general, we are interested in questions that require students to understand a pro-

gra m, procedure, or program fra gment. The code ma y be presented on pa per, it ma y be

ma de ava ilable electronically, or it ma y even be executa ble. The code ma y conta in

mea ningful comments or not. Ext erna l documenta tion of va rious forms ma y or may

not be a va ilable. We do not ha ve spa ce to explore these possibilities in detail. Clea rly,

however, certa in choices ma ke the sam e question easier or ha rder to a nsw er. Infor-

mation that is difficult to extract from raw source code can be very easy to find if pro-vided directly in comment s, for example. (More documenta tion is not a lwa ys helpful,

however.) When developing questions, it is importa nt t o a sk wha t knowledge and skills

we a re trying to test . When evalua t ing a possible question, i t is importa nt to ask w hat

knowledge and skills students will have to use (and therefore demonstrate) in order to

a nsw er it . These rules of thumb help us select questions an d appropria te source

materia ls .

For this report, we did what instructors often do as we developed our questions for an

CMU/SEI-90-EM-3 29

7/27/2019 90em003

34/173

exercise or examination, namely, made a few arbitrary decisions and took them as

given. Thus, w e wr ote a w ell-documented Ada progra m a nd developed questions for a

va riety of educa tional objectives based on tha t progra m. The progra m can be provided

on paper or electronically, in w hole or in part . Read ers can select sets of questions from

those provided to test their students, or they can augment our questions with theirown. If there is rea son to do so, they can remove comment s, cha nge sta tements , or

provide externa l documenta tion a long w ith t he source code.

Rea ding q uest ions ca n be mult iple-choice or free-response. One or more quest ions ca n

be a sked about a single pa ssa ge. It is a lso possible to ask student s to select one of

severa l passa ges as the answ er to a q uest ion. P ossible forms of essentially the same

question ar e illustra ted in the examples below , which ar e adopted from [Deimel85a]:

1. Wha t is th e appar ent purpose of the code below?

TEMP := A;A := B;

B := TEMP;

2. Wha t is th e appar ent purpose of the code below?

TEMP := A;A := B;B := TEMP;

a . S etA, B, and TEMP a ll to the same value.

b . Sort the va lues ofA, B, and TEMP.

c. Exchange the values ofA a nd B.

d . Sort the va lues ofA a nd B.

3. Which one of the following fra gments correctly a nd efficiently excha ngesthe va lues ofA a nd B?

a . T1 := A;T2 := B;B := T2;A := T1;

b. B := A;A := B;

c. TEMP := A;A := B;B := TEMP;

d. T1 := A;T2 := B;A := T2;B := T1;

The first question is a free-response question; the second and third are multiple-choice.

30 CMU/SEI-90-EM-3

7/27/2019 90em003

35/173

Multiple-choice questions ha ve the a dva nta ge of being ea sy t o grade a nd t o grade objec-

tively. Writ ing good mult iple-choice ques tions can be time-consu ming , how ever, a fact

tha t m a y offset a ny scoring efficiency ga ined. Multiple-choice questions seem most de-

sira ble if a la rge pool of th em ca n be developed over time. We have included a few

multiple-choice questions am ong the exercises. Sug gestions for ma king up such ques-tions can be found in [Deimel85a], w hich also discusses th e ass essment of how successful

part icular quest ions a re as evaluat ion instruments.

Various kinds of free-response quest ions a re possible. Often, only a sent ence or phra se

can provide the answ er. Essa y questions, however, require more extended composition

on the part st udents a nd expand ed effort on the par t of the instru ctor. Responses to

questions can be dia gra ms or other kinds of documents . Cloze procedure tests ha ve

a lso been used for testing progra m comprehension. In a cloze procedure question, ele-

ments of the program are deleted (say, every nth statement or every nth operand or

opera tor), and st udents a re required to supply the deleted elements. A simple example

might be:

1. Complete the fragment below, so that i t excha nges the values ofA a nd B:

TEMP := A;;

B := TEMP;

One of the most difficult a spects of generat ing rea ding comprehension questions is tha t

of producing a dequa tely diverse questions. The classificat ion scheme of Deimel and

Makoid [Deimel84] is an effective tool with w hich to deal with t his problem. Deimel and

Ma koid suggest using a tw o-dimensional classificat ion of question types. One axis

represents behavioral objectives in the cognitive domain (roughly speaking, the cog-

nit ive difficulty of th e opera tions requ ired to produce th e corr ect a nsw er). The oth er

axis represents the knowledge domain or domains (in Brookss terminology) aboutw hich one must rea son in order to answ er the question. A set of quest ions representing

question ty pes well distributed in t his tw o-dimensional ma tr ix should, in principle, be a

broad mea sure of reading comprehension. A set of questions tha t requires reas oning

only about individual statements, on the other hand, would likely measure overall

reading comprehension poorly.

The cognitive complexity axis uses Blooms taxonomy of behavioral objectives in the

cognitive domain [Bloom56, Bloom71]. This is a cla ssifica tion of types of beha vior w e

might w a nt to elicit from students. The taxonomy is hiera rchica l, a t least in principle,

in the sense that performance at any level requires the performance skills at all lower

levels. The levels of the hiera rchy a re a s follow s (w e offer brief explan a tions in the

domain of our int erest):

1. Knowledge: Knowledge-level tasks call for definitions, recognition, etc.The programmer is asked to respond with established facts about pro-grams and programming methods, or to give back, more or less verbatim,wha t he has read .

2. Comprehension: This level represent s simple under st a ndin g. The pro-grammer is asked to summarize or paraphrase what he has read, but isnot required to demonstra te deep underst a nding of it or its implica tion.

CMU/SEI-90-EM-3 31

7/27/2019 90em003

36/173

3. Application: This level involves the use of abstr a ctions in pa rt icula r a ndconcrete situa tions. At t his level, informat ion becomes functional, not justtheoretica l. The progra mmer might be asked to describe the behavior of aprogram.

4. Analysis: This level is concerned with the organization of informationa nd the relat ionships among elements. The program mer may be a skedabout program components, their organiza t ion, a nd how they w ork t ogeth-er .

5. Synthesis: Synthesis is the putt ing together of parts to form a whole.Writ ing a progra m or modifying a progra m a re synthesis ta sks.

6. Evaluation: The ma king of qua ntita t ive and qua litat ive judgements, re-quiring measurement a gainst criteria . The programmer might be askedto evalua te program efficiency, read a bility , etc.

Deimel and Makoid in [Deimel84] a nd [Deimel85c] list several specific types of reading

comprehen sion quest ions for each level. We w ill not reproduce th e list here, but w e

discuss some of these types in relation to particular questions we provide in the nextsection.

6.2. Example Program Reading Questions

We now present concrete examples of program reading questions based on the mul-

tit a sking Ada program provided in the Appendix. Our objectives a re thr eefold:

1. To show tha t mea ningful and va ried reading questions a re not diff icult toconstruct.

2. To illustra te part icula r kinds of questions to help educa tors w rite ques-

tions ma tched to their ow n par ticular educat iona l objectives.3. To provide actua l questions and a ssociat ed source code tha t can be as-

sembled by educa tors int o exercises and examina tions.

The questions are grouped by Bloom taxonomy levelroughly, in order of difficulty

though perhaps one should not ta ke this description too litera lly. This arr a ngement

facilitat es both discussion of question const ruction and a ccess by instr uctors, a t lea st t o

the extent th a t th ey think in terms of a bstra ct educat iona l objectives. The list is not so

long a s to preclude a linear sea rch for useful items. The questions are a vaila ble on

diskette (an order form is provided as an attachment), so searches of the question set

can be made with a text editor.

We have not provided an sw ers to questions. Although the rea son for this ha s more todo with the publication schedule than with anything more philosophical, the net effect

is not a ltogether bad. The lack of answ ers makes anyone who wa nts t o use the ques-

tions look seriously at the a ccompanying code. This, in turn , helps one see the a nsw ers

students will be asked to discover, appreciate the process students will need to go

through to find them, and ga in insight into the progra mhelpful for writing additional

questionsa nd into program rea ding generally.

32 CMU/SEI-90-EM-3

7/27/2019 90em003

37/173

We should point out th a t t hese questions are not field tested. We encoura ge readers to

create exercises or examinations from them and to share their materials and experi-

ences with others t hrough the Softwa re Engineering Inst itute.

A few words are in order about the Ada program on which the questions are based.

The progra m is a w ell-document ed, multit a sking progra m of a bout 800 sta tements . It

is distribut ed am ong 11 files, whose combined length is a bout 3800 lines. The ma in

procedure is pdi, w hich ca n be found in file pdi.a. The progra m sear ches (possibly verylarge) natural numbers in arbitrary bases to f ind what are called perfect digital

inva ria nts (P DI s) a nd pluperfect digital invaria nts (P P DI s). (The na tur e of these

numbers is not import a nt. The comments in the ma in procedure conta in background

informat ion an d references.) Significant fea tur es of the progra m include:

A multiple-precision integer arithmetic package, numbers.

A user-interaction capability that accepts user requests while searches arein progress.

Automatic checkpointing and restarting, a useful feature, as