WHEN IS THE JOB FINISHED?

Two frequently asked but often difficult to answer questions are: When is a maintenance task finished? When is a newly developed program ready for production? The primary difference in the answers is the level of

documenta-Table 12-6. Contents of a Header for a Main Program Title-one-line descriptive name of program

Author-name, address, and phone number of author

Date Wrlttenllmplemented-date when the program was authorized for creation or date of first production use (whichever is more significant) Function-paragraph that defines the purpose of the program, the source

of the inputs, the destination of the outputs, and any significant logical transformations in between that may not be readily obvious from reading the main program code

Revision Table-table showing, for each (known) version of the program:

Revision number or letter code

Date the new version went into production Name or initials of the update programmer

Change request code (to identify the programmer's notebook and main-tenance log entries for the revision)

One-line description of the reason for the revision

Subroutine and Function Table-table that describes, for each separate code module: type code (e.g., u-user, I-library), name, one-line descrip-tion of purpose

Peripheral Requirements Table-table that describes, for each peripheral device used:

Type code (i-input, o-output, s-scratch) Logical unit name and/or number in the program One-line description of use

Source or destination of the data

Exact control-card image (if any) used to assign the peripheral device to the run

References-bibliographic references to documentary information about the program, including background references for algorithms or procedures"

and manual references documenting unusual programming techniques Parameters and Restrlctions*-any situations in which data may be

inap-propriate for the use of this program

Formal Runstreams*-name, location, and purpose of canned runstreams to aid in program maintenance and use

• Optional

tion that can reasonably be generated before a program is handed off to production. Following the guidelines presented in this chapter greatly simpli-fies the question of when to hand off to production. Very briefly stated, a program is ready to be given back to its users when:

1. The test run using the benchmark data has been approved by the pro-grammer and the customer

2. The minidoc has been updated to reflect the change, and the user understands the new run setup form

The maintenance task is a slightly different matter; the programmer must also:

1. Bring the maintenance binder up to date 2. Complete and close the programmer's notebook

3. See that the maintenance or patch documentation is written, approved, and sent for distribution

4. Give all appropriate materials to the librarian and archivist to bring their files up to date

Table 12-7. Contents of a Header for a Subprogram

Access-information about where to find the module on a computer file (in-cludes version identification and date of most recent modification) Function-a few lines describing the purpose of the module

Inputs-name and short definition of each datum that is used within, but whose value is set outside, the module

Outputs-name and short definition of each datum whose value is set within, for use later outside of, the module

Revision Table*-as shown in Table 12-6.

Data/Parameter Deflnltions*-name and definition of significant data enti-ties; define any data held in global storage at this point

Equatlons*

Parameters and Restrictions*

References*-documents describing algorithms, procedures, or unusual programming practices used in the module

• Optional

When the librarian and archivist have also closed their files and the post-implementation review has passed without new changes being required, the maintenance project is finished.

CONCLUSION

Statistics indicate that maintenance may represent up to 80 percent of resource time and cost during the lifetime of a software system [3]. This knowledge, unfortunately, is rarely translated into adequate maintenance fa-cilities and resources. Part of the reason is that no one really understands what software maintenance entails nor how many people it takes to start a mainte-nance shop. A rule of thumb is that at least two people are needed at the outset: a programmer and someone in a general support function. Where the shop goes from there depends on a variety of factors, including:

• Size of system(s) being maintained

• Complexity of interactions among programs

• How often changes are requested

• How soon changes must be finished

• Whether a· design shop exists to trade new programs for old Probably the most important factor of all, however, is how well the code was initially written.

How can a system be designed for maintainability? This chapter has at-tempted to answer that question. If an organization practices good structured programming techniques, backed up by solid structured documentation prac-tices, and adds a formalized test and evaluation procedure for enhancements and updates, systems will be more maintainable from the start.

References

1. Shumate, Kenneth C., and Anderson, Gordon E. "Resolving DP Management Issues by the Numbers." Data Management, Vol. 18, No.2 (MIlICh 1980), 32-35.

2. Schneider, Gene, French, Don, and Lucas, Lee. "How to Document Software." Naval Weapons Center CCF-87. China Lake CA, August 1977.

3. Lientz. B.P., Swanson, E.B., and Tompkins, G.E. "Characteristics of Application Software Maintenance." Communica-tions of the ACM, Vol. 21, No.6 (June 1978), 466-471.