ADP  SYSTEM DOCUMENTATION STANDARDS
                             U.S. Environmental Protection Agency
                                          Prepared by:
                      Management Information and Data Systems Division
                                        U.S. Environmental Protectton Agency
                                        Library, Boom 3404  PM-3I1-A
                                        401 H Street, S.W.
                                        Washington, PC  20460
                                            .
                                          February 1980
t

-------
 f
                              TABLE OF CONTENTS
 t
                                                                                         Page
                  Section 1 - Introduction
1.1       Objectives	1-1
1.2       Software Development Within EPA  .   .   .   .	1-2

Section 2 - Functional Description

2.1       Summary	2-1
2.2       Table of Contents	2-2
2.3       Description	.....2-3

Section 3 - DataDictionary

3.1       Summary	3-1
3.2       Table of Contents	3-2
3.3       Description	3-3

Section 4 - UBer0B Guide

4.1       Summary	4-1
4.2       Table of Contents	  4-2
4.3       Description	4-3

Section 5 - Design Document

5.1       Summary	5-1
5.2       Table of Contents	5-2
5.3       Description	5-3

Section 6 - Implementation and Test Plan

6.1       Summary	  6-1
6.2       Table of Contents	6-2
6.3       Description	6-3

Section 7 - Programmer's Maintenance Manual

7.1       Summary	7-1
7.2       Table of Contents	7-2
7.3       Description	7-4

Section 8 - Coding Guidelines

8.1       Introduction	  8-1
8.2       Choice of Language	8-1
8.3       Programming Style	  8-2
8.3.1     What is Style?	8-2
I

-------
  f
                                  TABLE OF  CONTENTS  (continued)
8.3.2
8.3.3
8.3.4
8.3.5
8.4
8.4.1
8.4.2
8.4.3
8.4.4
8.5
8.5.1
8.5.2
8,5.3
8.5.4
8.5.5
                     Good Program Constructs .............  8-3
                     Consistent Language Usage  ........   ....  8-3
                     Use of Meaningful Mnemonics   ..*.   ......   .  8-3
                     Good Commenting  ..........   .   .   .   .   .  8-3
                     Program Layout ...........   .....  8-4
                     Prologs .......   ...........  8-4
                     Annotation .  .  ...............  8-7
                     Blocking of Statements ...................  8-7
                     Format ............  4  ..............  8-12
                     Coding Practices ..........  .  ...........  8-12
                     Efficiency .........................  8-12
                     Naming and Labeling Conventions   .......  ..... ..  8-17
                     Expression and Computational  Accuracy   ..........  .  8-17
                     Acceptable Program Structures   .  .......  .......  8-21
                     Language Usage and Restrictions   ..............  8-28
t
           Appendix A - Glossary

           Appendix B - Charting Conventions for System Development

           Appendix C - Biblography

                                       List of Illustrations
            1        Prolog (Full Form) 	 8-5
            2        Unseparated Code	8-8
            3        Code Divided Into Blocks and Separated by Headers  ..... 8-9
            4        Code Separated into Blocks	 8-10
            5        Unacceptable Use - Copy Lines of Code  *	8-11
            6        Uncommented Poorly Formatted Code  	 8-13
            7a,b     Well-Formatted and Commented Code  	 8-14,15
            8        Improving Readability  	 8-16
            9        Improving Readability  	 8-18
           10        Improving Readability	 8-19
           11        Program Structure Types  . 	 8-22
           12a,b     Sequence Structures  	 8-23,24
           13        Repetition Structures	8-25
           14a,b     Case Structures  	 8-26,27

                                          List of Tables

           Table                                                                 Page

            1        Overview of System Development Phases  ... 	 . . 1-4
                                              ii

-------
f
t
t
                  1.        INTRODUCTION
1.1       OBJECTIVES


Although the need for documentation has been recognized for many years, it
was often felt that annotated program listings and some form of user's guide
would satisfy the documentation needs of a program or system of programs.  It
has recently become evident, however, that such an approach to documentation
is so inadequate as to be practically worthless.  This is most apparent when
maintenance or enhancement is required or when a program or system is
transferred to a computer different from that on which it was developed.

There have been many attempts to address this problem by establishing guidelines
for documenting programs and systems, and indeed, these guidelines resulted
in documentation far superior to previous efforts.  They failed, however, in
one major aspect - they addressed documentation typically as a final discrete
step that was carried out after the subject system or program was completed.

Recent advances in software development methodologies, however, have demonstrated
that proper documentation Is not only an essential aspect of a system
development, but is also an integral part of the development process itself.
In light of these advances, the EPA has developed standards (based for the
most part on those published by the National Bureau of Standards in FIPS PUB 38)
for the key documentation products of Agency software development efforts.

It is the intention of the Agency to include these standards in the EPA ADP
Manual either by direct inclusion or by reference.  EPA data processing
personnel should use these standards when developing information systems In-
house, by contract, or by grant.  The standards included herein apply to
the various system development phases that follow a feasibility study.
Each phase has one or more documents associated with it as described below.
Standards for each of these documents are presented in subsequent sections
in the form of a sample Table of Contents, followed by descriptions of the
sections to be included in the document.  It is important to note that, although
each document is presented section by section, the primary purpose of these
standards is to indicate information that should appear in the subject
documents.  In addition to these standards, program coding guidelines for
COBOL, PL/1, and FORTRAN have been included below as a separate section.
These guidelines should be used by programmers during the implementation
phase.  Use of these standards is intended to provide EPA with more effective
information systems, and will provide a better basis on which to ensure
system viability during computer center changes or upgrades.
                                                      1-1

-------
 f
            1.2
          SOFTWARE DEVELOPMENT WITHIN  EPA
           The development and maintenance  of  software  systems within EPA has become a
           complex activity involving  many  organizations.  Development activities usually
           span a number of months and the  resulting  systems may be used in normal
           production for years.  Because of the  large  investment by the Agency In
           software, guidelines are essential  to  ensure that reliable and maintainable
           software is produced.  These guidelines must be flexible enough to be applicable
           to the wide variety of development  activities — from infrequently used batch
           reporting systems  to high use, on-line interactive systems.  In keeping with
           this, MIDSD has established guidelines for the development of software systems
           that include the phases described on the following page.  Table 1 provides a
           brief overview of  a typical system  development effort, including the processes
           involved and approximate resources  required.
 t
               Initiation

               Feasibility
                 (Also commonly referred to as a Concept Study, Functional
                 Requirements and Alternatives Analysis, or a Definition
                 Stage)

               System Design
                 (Also commonly referred to as Functional Design, General
                 Design, External Design, or System Architecture)

               Program Design
                 (Also commonly referred to as Detailed Design, or Internal
                 Design)

               Implementation

               Approval

               Evaluation
           The Initiation Phase is begun when a user identifies a problem that requires
           solving and, together with a system analyst, defines the scope of the
           problem and the objectives of its solution.  The brief written report
           produced in this phase is commonly referred to as a "System Concept
           Report."
t
The purpose of the Feasibility Phase is to define and scope out a particular
problem, to define and evaluate various alternative solutions, and to
recommend a selected alternative.  This work is documented in a Feasibility
Study report.  Guidelines for preparing and evaluating feasibility study
reports are available from MIDSD in a separate document.   Please note that,
when referring to the "Guidelines for Preparing and Reviewing Feasibility
Studies" document, Sections II.7 though II.9, which deal with system design,
have been superceded by standards included herein.
                                               1-2

-------
f
                   Generally speaking,  the guidelines presented  below complement  the feasibility
                   study  guidelines,  and provide standards for the system development process
                   that would logically begin after completion and management  approval of  a
                   feasibility study  recommending development of an ADP system.

                   The system development  process begins  with a  need to take the  general
                   concepts  of the  feasibility study and  to make them more concrete.   This is
                   analagous to an  architect's first rendering of a house, and marks  the
                   beginning of the System Design Phase  for the  proposed ADP system.   In this
                   phase,  the system  requirements are documented in a Functional  Description,
                   Data Dictionary, and a  draft User's Guide.  Guidelines for  these  documents
                   are included herein.

                   Next comes the Program  Design Phase in which  the detailed internal  structure
                   of the  system programs  are developed and presented in a Design document.
                   To continue the  analogy one more step,  this is comparable to the  detailed
                   construction drawings for  a house.  This structure should be developed
                   using an  established design methodology (e.g.,  Jackson, Yourdon, H1PO,
                   etc).   The Program Design  Phase is completed  by the  production of  a  unified
                   Implementation and Test Plan.

                   The Implementation Phase consists of coding,  testing,  and demonstrating the
                   system  as well as  any other  steps necessary to produce an operational system
                   (e.g.,  data conversion,  or capturing new data and establishing required  manual
                   procedures for the new  system).   During this  phase,  the Programmer's Maintenance
                   Manual  is produced.

                   The Approval  Phase consists  of  demonstrating,  through  separate system demonstrations
                   and/or  parallel  operations with an old  system,  that  the system operates  as
                   expected.   The final  User's  Guide is produced  during this phase.

                   The Evaluation Phase  is  performed shortly after  the  system  has been placed
                   into full production  use.  A report should  be  produced  that examines how
                   well the  original  objectives,  budgets,  and  schedules have been met.  Areas
                   that exceed or fall  short  of  expectations  should also  be included.
t
                                                      1-3

-------
f
                  Table 1.  (1 of  2)  Overview of  System Development Phases
      Phase
Products of Phase
Action at End
  of Phase
Personnel
Involved
      Initiation
System Concepts and
Objectives Report
and Management Plan
Management Decision to
Go or No-Go With
Feasibility Study
Management
Program Analysts
System Analysts
      Feasibility
Feasibility Study Report
Management Decision
to Go or No-Go With
System Development
Management
Users
Program Analysts
System Analysts
      System Design
t
      Program Design
Functional Description
Data Dictionary
Draft User's Guide
Program Design Report
Test and Implementation
System Manager and
Users Approve Functional
Design and Authorize
Further Development
System Manager and
Programming Manager
Agree on Design,
Plans for Test and
Project Control
System Manager
Users
Program Analysts
System Analysts
System Manager
Programming Manager
Programmers
      Implementation
      (See Note)
Programmer's Maintenance
Manual
System Manager Receives
a System Ready for Final
Test
System Manager
Programming Manager
Programmers
      Approval
Final User's Guide
System Manager and
Users Accept System
System Manager
Users
Programming Manager
Programmers
      Evaluation
Post-Implementation
Audit Report
Management Receives an
Evaluation of Project
Objectives, Schedules
and Budget
Management
Program Analysts
t
                                              1-4

-------
 f
                            Table  1.   (2 of 2)  Overview of  System Development  Phases
               Phase
                                         Estimated Time  and  Personnel  Resources To Complete
                                            Small System
                                                               Large System
                    Time      Work-Months
                    (Months)     (WM)
                         %WM      Time      Work-Months
                        	(Months)     (WM)
                                  %WM
               Initiation
                    1/2 - 1
                                    2-3
              Feasibility
                    1-2
                         17
           6-9       36
                       22
              System Design        1-2
                                             17
                                    4-6
                       30
                       19
I
              Program Design      1-2
Implementation
(See Note)
1 1/2-3
                                             17
25
                                    3-4
6-9
                       24
54
                       15
33
              Approval
                    1/2 - 1
                                    2-3
              Evaluation
                    1/2 - 1
                                    1-2
              Total
                    6-12
               12       100        24  - 36      162
                                 100
              (Note:  The cost of computer time during implementation is commonly estimated as
                      being equal to the implementation personnel cost.)
t
                                                      1-5

-------
f
2.    FUNCTIONAL DESCRIPTION

The system's Functional Description is produced during the System Design
Phase and is used to describe the external characteristics of the subject
system.  This description provides a basis of understanding between users
and designers with respect to the initial problem, system requirements,
and development plan.
I
t
                                                        2-1

-------
 f
                                             FUNCTIONAL DESCRIPTION
                                               TABLE OF CONTENTS
I
t
Section  1 -  Introduction	2-3

1.1          Overview	2-3
1.2          Environment	2-3

Section  2 -  System  Summary	2-4

2.1          Background	2-4
2.2          Objectives	2-4
2.3          Existing Methods and Procedures  	  2-4
2.4          Proposed Methods and Procedures  	  2-4
2.4.1        Summary of Improvements	2-5
2.4.2        Summary of Impacts	2-5
2.5          Assumptions  and Constraints  ............  2-6
2.6          Cost Considerations	.	2-6

Section  3 -  Detailed Characteristics 	  2-7

3.1          System  Functions 	  2-7
3.2          Performance  Characteristics  	  2-7
3.2.1        Accuracy and  Validity	2-7
3.2.2        Timing	2-7
3.2.3        Flexibility	2-8
3.3          Inputs	2-8
3.4          Outputs	2-8
3.5          Data Characteristics	2-8
3.6          Failure Contingencies  	  2-8

Section 4 -  Operational  Environment	2-9

4.1          Equipment	2-9
4.2          Support  Software 	  2-9
4.3          Interfaces	2-9
4.4          Security and  Privacy	2-9
4.5          Controls	2-9

Section 5 -  Development  Plan	2-10


Appendixes	2-11

Appendix A - ProjectReferences  	  2-12

Appendix B - Glossary	2-13
                                                          2-2

-------
f
                                            FUNCTIONAL DESCRIPTION
                                           SECTION 1  - INTRODUCTION
                1.1
OVERVIEW
                This subsection identifies the agency mission addressed by the system to be
                developed and summarizes the general nature of the system.
                1.2
ENVIRONMENT
                This subsection identifies the project sponsor or organization,  user,  develop-
                er (if known),  and the computer center or network where the  system is  to be
                implemented.
I
t
                                                     2-3

-------
   f
                                     SECTION 2 - SYSTEM SUMMARY
           2.1
           BACKGROUND
 I
t
           This subsection gives background information about the purpose and uses of
           the system so as to orient the reader.  It explains relationships with other
           software or procedures.
           2.2
           OBJECTIVES
           This subsection contains concise, quantified statements about the major
           performance requirements of the system.  Anticipated operational changes that
           will affect the system and its use are identified.
           2.3
          EXISTING METHODS AND  PROCEDURES
This subsection  describes existing methods used to satisfy current requirements.
Included is information on:

               Organizational and personnel responsibilities
               Required and available  equipment
               Inputs and outputs - their volume and frequency
               Deficiencies/limitations
               Pertinent cost information.

Included also are figures and appropriate narrative to help the reader better
understand the existing system.  At least one chart should be included which
illustrates the  overall processing flow for the existing system.  It should
identify inputs, functions performed,  and outputs.  Major inadequacies of the
current system are described.

2.4       PROPOSED METHODS AND PROCEDURES

This subsection  describes the proposed system.  A chart depicting the proposed
data flow and processing should be included with appropriate narrative.
Other illustrations should be included as necessary to provide a more thorough
understanding of that which is being proposed.  Information on the following
should also be included:

               Organizational and personnel responsibilities
               Required and available  equipment
               Inputs and outputs - their volume and frequency
               Deficiencies/limitations
               Pertinent cost information {developmental as well as operational).

Techniques and procedures borrowed from other systems are identified.
Operational functions available to the user are explained.
                                                2-4

-------
                 2.4.1
          Summary of Improvements
                 This  subsection gives a summary of the benefits to be obtained from the
                 proposed system.   It  should include a  comparison between deficiencies  identified
                 in Section 2.3  and additional capabilities provided by the proposed system.
                 The improvements may  be categorized as:

                                New capabilities
                                Improved existing capabilities
                                Timeliness  (response time,  processing time)
                                Elimination of existing deficiencies
                                Elimination or reduction of existing capabilities  that  are no
                                longer needed.
                 2.4.2
          Summary of Impacts
 t
t
This subsection lists the anticipated impacts and associated costs of the
proposed system on the present system as follows:

          »    Equipment Impacts  - Changes to current equipment and build-
               ings.

          •    Software Impacts - Changes to existing software in order to
               adapt  them to the proposed system.  If the proposed system
               eliminates or degrades any capabilities in the existing
               system, these capabilities must also be described, as well
               as the reasons for their elimination or degradation.

          •    Organizational Impacts - Personnel impacts as a result of
               implementing the proposed system.   Discuss any modifi-
               cations in positional responsibilities as a result of imple-
               menting the new system.

          •    Operational Impacts - Changes required in both staff  and
               operations center procedures.  Discuss Impacts on the
               relationship of the operating center and the user;  new data
               sources;  quantity,  type, and timeliness of data to be pro-
               vided;  data retention and data retrievals;  methods of report-
               ing; and  modes of user access.   Also include recommended
               methods for providing input data if these data are not
               already available.

          *    Developmental Impacts - User efforts required prior to
               installation of the system,  such as manpower required to
               develop a data base,  and operator  and computer time necess-
               ary  for testing.   Also identified  are requirements for
               conversion efforts.   Exceptional levels of  staffing or
               computer  time required for the  parallel operation of  the
               new  and existing systems should be discussed.
                                                     2-5

-------
f
          2.5
ASSUMPTIONS AND CONSTRAINTS
          Any assumptions  and  constraints  that  will  affect  development and operation  of
          the system will  be discussed.  Any  limitations  affecting the desired capability
          and explicit  identification of any  desired capabilities that will not  be
          provided  by the  proposed  system  are discussed.  Examples of assumptions
          include organizational  actions,  budget  decisions,  operational environment and
          staffing  requirements.  Examples of constraints include operation environment,
          operator  skill level, human factors (man/machine  interface), budget limitations
          or development schedules.
          2.6
COST CONSIDERATIONS
          This  subsection  describes  resource  and  cost  factors  that may influence the
          development,  design,  and continued  operation of  the  proposed software.  Also
          discussed are other factors which may determine  requirements, such as interfaces
          with  other  systems.
I
f
                                               2-6

-------
              3.1
          SYSTEM FUNCTIONS
t
              This subsection briefly Ascribes all functions ~.-'d ojvv »tional capabilities
              provided by the proposed *ysteic.  Each is  listed with a unique identifying
              number for easy correlation with individual requirement* described in other
              project 'references such as the design document and test plan.
              3.2
          PERFORMANCE CHARACTERISTICS
              This subsection describes the specific performance characteristics of the
              proposed system.  Each characteristic should be listed with an identifying
              number to facilitate referencing from other system documents.  The performance
              characteristics should be organized according to the following categories.
              3.2.1
          Accuracy and Validity
Briefly describe the accuracy considerations of the proposed system.  The
following must be considered:

          •    Accuracy requirements of mathematical calculations

          •    Accuracy requirements of data

          •    Data validation requirements.

3.2.2     Timing

Briefly describe the timing characteristics of the proposed system.  The
following should be considered:

          •    Throughput time

          •    Response time to queries and to updates of data files

          •    Response time of major functions

          •    Priorities imposed by types of inputs and changes to modes
               of operation

          •    Sequencing and interleaving programs and systems (including
               the requirements for interrupting a program without loss
               of data).
                                                   2-7

-------
  f
 I
            3'2*3     Flexibility

            Describe the capability for adapting to changes in requirements, such as:

                           Changes in mode of operation
                           Operating environment
                           Interfaces with other software
                           Accuracy and validation timing
                           Planned changes or improvements.
            3.3
          INPUTS
            This subsection provides examples and explains the various data inputs,
            specifying medium,  format, range of values, accuracy, etc.
            3.4
          OUTPUTS
            This  subsection provides examples and explains the outputs of  the proposed system.
            Included  are  quality control outputs that may have been identified,  descriptions
            and examples  of hardcopy reports,  and display outputs.
            3.5
          DATA CHARACTERISTICS
This subsection discusses the storage of the data elements to be used by the
application.  It includes information on specific data elements by name and
size, if known.  It also discusses dictionaries, tables, and reference files,
if applicable.  It includes estimates of total storage for the data and
related components based on a summation of the requirements.   It describes
the expected growth of the data and related conponents.
           3.6
          FAILURE CONTINGENCIES
t
           This subsection discusses  possible  failures  of  the hardware or software system,
           the consequences  of  such failures,  and  the alternative courses of action that
           may satisfy the information  requirements.  It includes, as appropriate:

                     •    Backup - Specify backup  techniques.  For example, a backup
                          technique for disk would be to periodically copy the disk
                          to a  tape.

                     •    Fallback -  Explain the fallback  techniques, i.e., the use of
                          other means to accomplish some portion of requirements.  For
                          example, a  fallback  technique for an automated system might
                          be manual manipulation and recording of data.

                     •    Recovery and  Restart - Discuss recovery and restart techniques,
                          i.e., the capability to  resume execution of software from
                          a  point at  which a problem occurred.
                                                2-8

-------
                      :             -^ 'UTIUKAL ENVIRONMENT


4.1        '-OUIPMI.NT

This sub.s«cv..lon  describes  t^t  _qu^pT2nt capabilities required by the system.
Equipment  sh-.-uld be  de.3-.--.riV ~.  ?
-------
                         SECTION 5 - DEVELOPMENT PLAN
This section discusses the overall management approach to the development and
implementation of the proposed system.  It includes a list of the documentation
to be produced, time frames and milestones for the development of the system,
and necessary participation by other organizations to assure successful development.
                                    2-10

-------
                                  APPENDIXES
These sections contain supporting information and lists which for the sake
of convenience and readability are left out of the main sections of this
document.  The two described here (Project References and Glossary) are
required.  Additional appendixes may be added as appropriate.  The order
in which the appendixes occur is Incidental.
                                     2-11

-------
                       APPENDIX A -PROJECTREFERENCES


This appendix contains a summary of related pertinent documents or monographs.
Examples are:

          •    Operating system reference manuals

          •    System processor reference manuals (e.g., Text Editor)

          •    Requirements documents

          •    Mission definition documents.
                                     2-12

-------
                            APPENDIX B - GLOSSARY
The glossary is an alphabetic list of special terms, initials, and
acronyms (and their definitions) that are used in this document.
                                     2-13

-------
"
                3.   DATA DICTIONARY
                The Data Dictionary is produced during the Syg^am Design Phase and is
                intended to present the various data items required by the system so that
                they may be readily identified, defined, represented, and structured.  It
                should be noted that the Data Dictionary describes only those data items that
                enter the system from the outside world or those items that are produced by
                the system for use outside the system.  Data icems that exist wholly
                within the system are of no concern at this time.
                                                     3-1

-------
                               DATA DICTIONARY
                              TABLE OF CONTENTS
Section 1 - Introduction
 Page




,  3-3
Section 2_-; Data Dictionary	3-4









Appendixes . . . .	3-9




Appendix A - Group/Category Cross-Reference  	 .... 3-10




Apj>endix B - Record Cross-Reference	3-11




Appendix C - File Cross-Reference	3-12




Appendix D - Data Item Cross-Reference	3-13
                                     3-2

-------
                                                  SECTION 1 - INTRODUCTION
                       This section describes the content and organization of this document.  It
                       also identifies the data base being addressed and describes its organization.

t
                                                            3-3

-------
                         SECTION 2 - DATA DICTIONARY
This section contains a description for each named data entity in the data
base.  Each description nust not exceed one page in length.  There are four
general, organizational entities for which description formats are provided.
They are the individual data item, the data group or category, the record,
and the file.  A data item is a single element of data - the smallest unit of
data that can be accessed.  A data group or category is a number of data
items or groups of data items which are grouped together logically but which
nay be distributed over more than one physical entity of a file or data base.
A record is a collection of data items which are physically grouped together
and form a constituent entity in a file or in a data base.  A file is an
organized collection of records.

Some systems allow for the naming of each of these entities and others permit
the naming of only a subset of these.  Each named entity is described according
to one of the formats which follow.  They are presented in this section in
alphabetic order regardless of entity type.  To faciitate rapid reference,
the entity name may also appear in the upper right corner of each page.
                                     3-4

-------
                            DATA ITEM DESCRIPTION
Data Item Name - The name by which the item is most commonly known.  In
          some cases, this name is different from that by which it is
          referred to in the data base dictionary.  The DBMS dictionary
          name can be mentioned separately or with the aliases mentioned
          below and flagged in some way to identify it as the DBMS
          dictionary name.

Alias Names (Synonyms) - A list of other names, in alphabetical order,
          by which the item is known.

Description - A brief (one- or two-sentence) English language statement
          describing the meaning of the item.

Type and Length - A designation of the item as being alpha, numeric,
          alphanumeric, blank, or special character string and the
          maximum length of the item in number of characters.

Security/Accessibility - Information regarding access to instances of the
          item in a file or data base.

Source - The source(s) from which the data item is obtained.

ValldatjxMi - A specification of validation criteria (e.g., a range of
          values).

Category/Group - The name of a group or set of data items in which the item
          falls.

File(s) - The name of the file(s) in which the item appears.

Edit Considerations - Information regarding the addition, deletion, and
          modification of the data item.
                                     3-5

-------
                               GROUP  DESCRIPTION
Group Name - The name  by which  a  group  or  category  of  data  items  Is
          most commonly known.  In  some cases,  this is different  from
          that by which it  is referred  to  in  the  data  base  dictionary.
          The DBMS dictionary name  can  be  mentioned separately or with  the
          aliases mentioned below and flagged in  some  way to identify it
          as the DBMS  dictionary  name.
Alias Names  (Synonyms) - A  list  of other names, in alphabetic order, by
          which the group is known.
Description - A brief English  language statement describing the meaning
          of the group or category.
Security/Accessibility - Information regarding access to the group of data
          items in a file or data base.
Source - The source(s) from which items in the group are obtained.
File - The names of files containing data items in the group.
Content - An alphabetic list of data items and/or groups that make up
          the group.
                                     3-6

-------
                              RECORD DESCRIPTION
Record Name - The name by which the record is most commonly known.
Alias Names (Synonyms) - A list of other names in alphabetic order by
          which the record is known.
Description - A brief English  language statement describing the record.
Content - An alphabetical list of data itens and/or groups contained within
          the record.
File - The name of the file in which the record occurs.
Source - The source(s) from which data items are obtained for inclusion
          in the record.
Edit Considerations - Information regarding addition and deletion of the
          record type and modification of the data within the record.
                                     3-7

-------
                                           FILE DESCRIPTION
            File Name - The proper name by which the file is known.
            Alias Names (Synonyms) - A list of other names by which the file is known.
            Description - A brief English language statement of the purpoge of the
                      file.
            Security/Accessibility - Information regarding access to and update of
                      the file.
            Source - The sources of data for inclusion in the file.
            Content - An alphabetic list of named records which make up  the  file.
            Media - Disk,  magnetic tape,  card,  etc.
            Organization - Physical organization of the  file (i.e.,  random,
                      sequential,  indexed sequential,  etc.)
t
                                                 3-8

-------
 F
                                                   APPENDIXES
                Various  cross-references  of data entities  are  presented  in the  appendixes.
                They  facilitate  the  identification of  related  and  constituent data  entities
                from  the name  of a single entity.   The cross-references  described in  the
                following pages  are  examples of  the types  of cross-references that  may  be
                developed for  a  particular system;  others  may  be developed as appropriate.
f
                                                     3-9

-------
                 APPENDIX A - GROUP/CATEGORY CROSS-REFERENCE
This appendix lists in alphabetic order the names of all data groups and
gives in alphabetic order the proper names for each data item or subgroup in
each group.
                                    3-10

-------
                     APPENDIX B - RECORD CROSS-REFERENCE
This appendix lists in alphabetic order the names of all records and gives
in alphabetic order the names of all data items in each record.

                                     3-11

-------
                      APPENDIX C - FILE CROSS-REFERENCE
This appendix lists in alphabetic order the names of all files and gives
In alphabetic order the names of all records in each file.
                                      3-12

-------
                    APPENDIX D - DATA ITEM CROSS-REFERENCE
This appendix lists in alphabetic order all possible names, proper and
alias, for all possible data entities.  The proper names have no cross-
reference presented.  The alias names are cross-referenced to the appropriate
proper name.
                                     3-13

-------
                       4.   USER'S GUIDE
*•  1
                       A draft User's Guide is produced during the  System Design Phase and is
                       finalized during the Approval Phase.  A prime consideration for producing
                       a draft User's Guide is that it allows the user to determine his/her
                       role in the final system before any serious  misconceptions are implemented.
                                                            4-1

-------
                                 USER'S GUIDE
                              TABLE OF CONTENTS
                                                                    Pa
Section 1 - Introduction	•	4-3

1.1       Purpose	4-3
1.2       User Profile	4-3

Section 2 - System Summary	 4-4

2.1       Overview	 4-4
2.2       Operational Environment  	 4-4
2.3       System Configuration 	 4-4

Section 3 - System Operation	4-5

3.1       Common System Initiation Procedures (if several processes
          are described)	4-5
3.2       Process 1 Description	 4-5
3.2.1     Security	4-5
3.2.2     Initiation Procedures  	 4-5
3.2.3     Operational Procedures 	 4-5
3.2.4     Error and Recovery Procedures	4-6
3.2.5     Constraints/Limitations  	 4-6
3.2.6     Data Base	4-6
3.2.7     Control Language	 4-6
3.2.8     Input	4-6
3.2.9     Output	4-7
3.3       Process 2 Description (each described system process
          includes the subsections given for Section 3,2)


Appendixes ...... 	 .... 4-8

Appendix A - Project References	 4-9

Appendix B - Glossary	 4-10

Appendix C - Diagnostic Messages 	 4-11

Appendix D - Control Instructions  	 ... 4-12

Appendix E - Input Vocabulary/Query Language 	 4-13
                                        4-2

-------
                                 USER'S GUIDE
                           SECTION 1 - INTRODUCTION
1.1
PURPOSE
This subsection briefly describes the purpose of the system being discussed -
the reason for its existence.  It relates the system to a particular agency
mission.
1.2
USER PROFILE
This subsection identifies the organization for which the use of this system
is intended.  It describes the person(s) for whom this document is intended.
It expresses whatever assumptions are made about the users, their capabilities
and their level of expertise.  It also identifies related systems, programs
and/or operational procedures with which the user should be familiar.
                                     4-3

-------
                          SECTION 2 -  SYSTEM SUMMARY
2.1
OVERVIEW
This subsection is a high-level description of what the system does.  It
identifies and summarizes the input and relates the processing that is
performed to the output that is produced.  Types of input are identified as
either required or optional.  If a system with several operational capabilities
is being described, all such capabilities are briefly described, as are the
relationships between them.  A system  flow diagram is included and the
substance of this subsection may consist entirely of a narrative description
of that diagram.
2.2
OPERATIONAL ENVIRONMENT
This subsection identifies the host computer(s), operating systera(s), executive
software system, and other major system components with which the system must
interface.  If it is part of a sequential processing environment, the processing
that immediately precedes and/or prepares input for this process is identified,
as is the processing which immediately follows.
2.3
SYSTEM CONFIGURATION
This subsection briefly relates the computer type and model and the required
input and output devices.  If the hardware configuration may vary, both ideal
and minimal configurations are described.  Any support equipment (such as
plotters) that may be needed is also included.
                                     4-4

-------
                          SECTION  3 - SYSTEM OPERATION
3.1
COMMON SYSTEM INITIATION PROCEDURES
Procedures  that must  be  followed to initiate system operation will be detailed
in this subsection.   It  nay include information such as  job request forms,
control card formats, or log-on procedures for on-line operations.  If these
procedures  are standard  or are detailed in another manual, that manual will
be referenced.

For a system with several operational capabilities, this subsection describes
preliminary operational  procedures that are common to the various system
capabilities.  If a single program or operational capability is being described
in this document, this subsection may be omitted.
3.2
PROCESS 1
The function(s) of the first process whose operational characteristics are
described in the subsections that immediately follow.  Section 3.2 (including
3.2.1 through 3.2.9) will be repeated for each process that is described.
3.2.1
Security
The procedures that should be followed to use input, files, data bases,
output, or computer prograns to which access is restricted are included.
3.2.2
Initiation Procedures
A step-by-step description of the operational procedures for starting up the
program or particular operational capability, including the same type of
information discussed in Section 3.1 as it pertains to the program
or system capability.  Examples of job deck construction, setup information,
loading procedures, and instructions for input data preparation would be included.


3.2.3     Operational Procedures

Step-by-step procedures for interfacing with this system capability are presented.
                                     4-5

-------
3.2.4     Elrror  and  Recovery  Procedures

All known anomalous  conditions  are  described with  references  to the  corresponding
diagnostics  listed in  Appendix  C.   Appropriate  recovery  procedures for
each condition are also  described.

3.2.5     Constraints/Limitations

This subsection  discusses  any restrictions  that may  be imposed.

3.2.6     Data Base

This subsection  describes  data  base files that  are referenced,  supported, or
kept current by  the  system.  They are  referred  to in  operational or  functional
terms rather than by program designation.   The  description includes  the type
of data in the files,  the  uses  made of the  data, and  the  various keys by which
data can be accessed.

3.2.7     Control Language

This subsection  describes  the control  language used  to control  the initiation
ar.d sequencing of runs in  either batch or on-line mode and the query language
used to reference the  data base.  The  description includes the  requirements
for, and the preparation of, control cards  which may  be required by  the system
or application process.  If this information is contained in other support            /*
documentation, that  source nay  be referenced.  The syntax of a query language
is described in  detail sufficient for  the uninitiated to develop the full
range of data base inquiry that is  periaitted.  Summaries of the control language
and of the query language may be Included as appendixes (see Appendixes D and E)
for easy reference.

3.2.8     Input

This subsection  discusses all inputs for this process and any interrelation-
ships which may  be helpful to its understanding.  A clear, detailed  description
of each valid input  is given in separate subsections.  Valid input is
that set of data which is recognized by the system (although it may  contain
erroneous fields); it  is to be clearly defined.  Invalid data is that which is not
valid - that is, data which is not  recognized by the  system and which may
either crash the system or produce  unpredictable results.  Such invalid data
should be discussed  to whatever extent is both possible and meaningful.
Valid data is described in terms of  the characteristics listed below.
Samples of completed data layout forms and  input data formats and sequences will
be included. The data  characteristics  to be included are given below.
                                     4-6

-------
3.2.9
•    Medium - The physical  form of the input

•    Length — Maximum number  of characters per line or per record

•    Content

•    Format

•    Punctuation - Spacing  and use of symbols (e.g., slash, asterick,
     character combinations)  to denote start and end of input,
     lines, or data groups, etc.

•    Sequencing - Order of  items in the input

•    Labeling - Use of tags or identifiers to denote major data
     sets

•    Combinations - Rules forbidding use of particular characters
     or combinations of parameters.


Output
This subsection describes all nondiagnostic output.   Each type of output
is described in a separate subsection which contains the following
information:

          *    Purpose - The way in which the output is utilized

          •    Medium - The physical forn of the output

          •    Format

          •    Examples

          •    Security - Distribution and access considerations

          *    Files - content, organization, record structure

          •    Data Base - content,  key information.
                                     4-7

-------
                                  APPENDIXES
These sections contain supporting infornation and lists which for the sake of
convenience and readability are left out of the main sections of this document.
The first three described here (Project References, Glossary, and Diagnostic
Messages) are required.  Any of the others can be eliminated if not pertinent
and additional appendixes may be added as appropriate.   The order in which
the appendixes occur is incidental.
                                     4-8

-------
                                        APPENDIX A - PROJECT REFERENCES


                 This  appendix contains a summary of related pertinent documents  or monographs.
                 Examples  are:

                           •    Operating system reference  manuals

                           •    Systen processor reference  manuals  (e.g.,  Text  Editor)

                           •    Requirements  documents

                           •    Mission definition documents.
t
                                                     4-9

-------
•
                                                  APPENDIX B - GLOSSARY
                      The glossary is ai\ alphabetic list of special terns, initials, and acronyms
                      (and their definitions) that are used in this document.
    I
                                                          4-10

-------
                                         APPENDIX C - DIAGNOSTIC MESSAGES
                  All diagnostic and error messages that are output by the software described
                  in this document are listed in this appendix.   Each diagnostic will have a
                  unique identifying reference number by which it can be referred to in other
                  sections of this document.
f
                                                      4-11

-------
                                 APPENDIX D - CONTROL INSTRUCTIONS
           Described in  this  appendix are specific references  of  input  commands  or
           operational procedures that perform a  single  function  and which  might, for
           the sake  of convenience,  be better  referred to  by a  single  term  in Sections
           3.1,  3.2.2, or  3.2.3 (Common System Initiation,  Initiation,  and  Operational
           Procedures).
f
                                               4-12

-------
                 APPENDIX E - INPUT VOCABULARY/QUERY LANGUAGE
This appendix lists the verbs and keywords that are required to interface
with the software described in this document.   A brief description of the
function and/or meaning of each word is included.
                                     4-13

-------
                         5.
DESIGN DOCUMENT
                         The Design Document is produced during the Program Design Phase.  This documej
                         is intended for use by analysts and programmers during the Implementation
                         Phase and contains precise specifications relating to the internal structure
                         of the subject system or program.
I
                                                             5-1

-------
                                           DESIGN DOCUMENT
f
                                          TABLE OF CONTENTS

                                                                                  Page

            Section 1  - Introduction	5-3


            Section 2  - Summary of Requirements	5-4

            2.1        System Description	  .  .  .  5-4
            2.2        System Requirements  	  ......  5-4
            2.2.1      Performance  Requirements  	  5-4
            2.2.2      Functional Requirements   	  5-4
            2.2.3      User  Requirements   	  ..........  5-4
            2.2.4      System Interface  Requirements  	  ...  5-4

            Section 3  - Environment	5-5

            3.1        Equipment Environment	5-5
            3.2        Support  Software  Environment .........  	  5-5
            3.3        Interfaces	  5-6
            3.4        Security and Privacy	  5-6
            3.5        Controls	5-6

            Section 4  - Design Characteristics    ..... 	  5-7

            4.1        Operations	5-7
            4.2        System Logical  Flow  	 .....  5-7
            4.3        System Data	5-7
            4.3.1      Inputs .....  	  5-7
            4.3.2      Outputs	  5-8
            4.3.3      Data  Base	5-8

            Section 5  - Program Specifications  	  5_9

            5.1        Subsystem  A	5-9
            5.1.1      Program  (Identify)  Specification 	  5-9
             •
             •
             •
            S.l.n      Program  (Identify)  Specification 	  5-9


            Appendixes 	 .....  5-10

            Appendix A - Project References  	 .....  5-11

            Appendix B - Glossary	5-12
                                                     5-2

-------
                                                DESIGN DOCUMENT
                                            SECTION 1 - INTRODUCTION
                 This section summarizes the circumstances and events leading to the development
                 of this design.  It identifies the agency mission that is being addressed and
                 the project sponsor or organization.  It summarizes the general nature of the
                 system, briefly describing the operational problem that is being solved.   Any
                 studies or reports which bear significantly on the design approach are referenced.
I
                                                      5-3

-------
                               SECTION 2 ^ SUMMARY OF REQUIREMENTS
          This section provides a summary of the system characteristics and requirements.
          It is an extension of the Functional Description document.  Any changes to
          the characteristics or requirements set forth in the Functional Description
          must be specifically identified.
          2.1
SYSTEM DESCRIPTION
          This subsection provides a general description of the system to establish a
          frame of reference for the remainder of the document.  Higher order and
          parallel systems and their documentation will be referenced as required to
          enhance this general description.  Also included will be a chart showing the
          relationships of the user organizations to the major components of the system
          and a chart showing the interrelationships of the system components.  These
          charts shall be based on or be updated versions of the charts included in the
          Functional Description document.  The detailed charts included in Section 4
          are based on the charts included here.
          2.2
SYSTEM REQUIREMENTS
          This subsection lists the requirements which must be addressed by the system
          being designed.  The requirements must be stated to permit a discernable
          means of proving that each has been fulfilled.  For ease of reference, each
          requirement should have a unique identifying number.  General requirements
          should be stated and then broken down into appropriate lower levels of detail.
          A cross-reference table or chart which relates requirements to subsystem,
          subroutine, module, or component is desirable.  The requirements should be
          categorized.  Some possible categories are suggested below.
          2.2.1          Performance Requirements
          2.2.1.1        Timing
          2.2.1.2        Accuracy and Validity
          2.2.1.3        Flexibility
          2.2.2          Functional Requirements
          2.2.2.1        Function 1
          2.2.2.1.1      Subfunction 1
          2.2.2.1.2      Subfunction 2
          2.2.2.2        Function 2
f
          2.2.2.n
          2.2.3
          2.2.4
     Function n
     User Requirements
     System Interface Requirements
                                               5-

-------
                                             SECTION 3 - ENVIRONMENT
                  This  section  provides  an expansion of  the  environment  given  in  the Functional
                  Description document.   Changes in the  environment  that do  not affect  the
                  scope of  the  project as described in the Functional  Description and are the
                  result  of  ongoing  analysis  and design  will be  explicitly identified within
                  the appropriate  subsections of this  section.   These  changes  will be discussed
                  in terms  of the  impacts on  the currently available environmental components
                  (equipment, software,  etc.) as well  as the impacts on  estimates and functions
                  which were based on the original  planned environment.
                  3.1
          EQUIPMENT ENVIRONMENT
 f
This subsection provides a description of the equipment required for the
operation of the system.  Included will be descriptions of the equipment
presently available as well as a more detailed discussion of the characteristics
of any new equipment necessary.  Equipment requirements will be related to
the requirements stated in the Functional Description document.  A guideline
for equipment to be described follows:

          1.   Processors), including number of each on/off-line and size of
               internal storage

          2.   Storage cedia, including number of disk units, tape units,  etc.

          3.   Input/output devices, including number of each on/off-line

          4.   Communications net,  including line speeds.
                 3.2
          SUPPORT SOFTWARE ENVIRONMENT
                 This subsection provides a description of the support software with which the
                 computer programs to be developed must interact.  Included will be both
                 support software and test software, if needed.  The correct nomenclature and
                 documentation references of each such software system, subsystem, and program
                 shall be provided.  Included must be a reference to the languages (compiler,
                 assembler, program, query, etc.), the operating system, and any Data Base
                 Management System (DBMS) to be used.  This description must relate to and
                 expand on the information provided in the Functional Description document.
                 If operation of the computer programs to be developed is dependent upon
                 forthcoming changes to support software, the nature, status, and anticipated
                 availability date of such changes must be identified and discussed.
f
                                                      5-5

-------
                   3.3
INTERFACES
                   This subsection  provides  a  description  of  the  interfaces with other applications
                   programs, including  those of  other  operational  capabilities and froa other
                   EPA organizations.
                   3.4
SECURITY AND PRIVACY
                   This subsection  describes  the overall security and privacy considerations of
                   the system.   If  none are  inposed, a statenent to that effect roust be made.
                   3.5
CONTROLS
                   This subsection describes any operational controls imposed on the system and
                   identifies the sources  of these controls.

I
                                                        5-6

-------
I
                                       SECTION  4-  DESIGN1  CHARACTERISTICS


                4.1       OPERATIONS

                This subsection  describes  the  operational characteristics  of  the  system and
                the computer  centers  where the software will  be  installed.

                4.2       SYSTEM LOGICAL FLOW

                This subsection  presents a high-level  discussion of inputs, processing
                performed, and outputs produced.   The  logical  flow of the  system  is depicted
                in high-level charts  which provide an  integrated presentation of  system
                dynamics, entrances and exits, interfaces with other programs, support
                software, controls, and data flow.

                If the scope  of  this  document  is the design of a system, this subsection will
                describe the  orderly  set of subsystems that make up the system.   If the scope
                of this document is an individual  subsystem or program, this  subsection
                relates lower level functions  to an orderly set  of named routines.

                4.3       SYSTEM DATA

                This subsection  describes  the  inputs,  outputs, and data used.  Optionally,
                these may be  described with the  individual programs to which  they relate.

                4.3.1     Inputs

                Each input will  be described as  follows:


                          •    Title  and tag

                          •    Format and  acceptable range of values

                          •    Number of items

                          •    Means  of entry  and  input initiation procedures

                          •    Expected volume and frequency, including special handling
                               (such  as queuing  and priority handling) for high-density
                               periods

                          •    Priority (e.g., routine, emergency)

                          •    Sources, form at  source, and disposition of source documents

                          •    Privacy and security considerations

                          •    Requirements for  timeliness.
                                                      5-7

-------

    f
4.3.2     Outputs

Each output will be described as follows:

          •    Title and tag

          •    Format, including headings, line spacing, arrangement,
               totals, etc.

          •    Number of items

          •    Preprinted form requirements

          •    Means of display (e.g., CRT, printer, typewriter, projector,
               alarm type, internal)

          •    Expected volume and frequency, including special handling (such
               as queuing and priority handling) for high-density periods

          •    Priority (e.g., routine, energency)

          •    Timing requirements (e.g., response time)

          •    Requirements for accuracy

          •    User recipients and use of displays, such as notification,
               trends, or briefings

          •    Privacy and security considerations.

4.3.3     Data Base

Each data file, table, dictionary, or directory will be described as follows:

          •    Title and tag

          •    Description of content

          •    Estimate of number of records or entries

          •    Storage, including type of storage, estimates of amount of
               storage and, if known, beginning and ending addresses

          •    Privacy and security considerations

          •    Data retention.
f
                                                           5-8

-------
                                        SECTION 5 - PROGRAM SPECIFICATIONS
                  This section identifies and describes the individual software units constituting
                  the system, subsystem, or program.  If the scope of this document is the
                  design of a system, the program descriptions which follow are grouped according
                  to subsystem.   Utility routines are to be grouped as a utility subsystem.
                  5.1
SUBSYSTEM A
                  This subsection describes the aggregate functions performed by the programs
                  or subroutines that are described in the subsections which follow.  It also
                  identifies the requirements listed in Section 2.2 that are addressed by this
                  software.   If the scope of this document is the design of a system, this and
                  the following subsections are repeated for each subsystem.  Programs which do
                  not fall into the category of any specific subsystem should be grouped under
                  a general category such as Library Routines or Utility Routines.
                  5.1.1
Program (Identify) Specification
                  This subsection identifies the functions performed by  the program and describes
                  the procedures employed to provide those functions.  The  types  of information
                  to be provided are as follows:

                            •    Calling sequence and argument description

                            •    Inputs/outputs

                            •    Program logic

                            •    Error conditions and their disposition

                            •    Significant design considerations
                  S.l.n
Program (Identify) Specification
                  A subsection,  as described above,  is provided for each program (1  through  n)
                  within the system.
f
                                                       5-9

-------
                                             APPENDIXES
           These sections contain supporting information and lists which for the sake of
           convenience and readability are left out of the main sections of this document.
           The two described here (Project References and Glossary) are required.
           Additional appendixes may be added as appropriate.  The order in which the
           appendixes occur Is Incidental.
f
                                                5-10

-------
                                                 APPENDIX A -  PROJECT  REFERENCES


                         This  appendix  contains  a summary of  related  pertinent documents  or  roonograpf
                         Examples  are:

                                    •     Operating system reference manuals

                                    •     System processor reference manuals  (e.g., Text Editor)

                                    •     Requirements  documents

                                    •     Mission  definition documents.
I
                                                              5-11

-------

                                      APPENDIX B - GLOSSARY
          The glossary is an alphabetic list of special terms, initials,  and
          acronyms (and their definitions) that are used in this document.
f
                                                5-12

-------
 6.   IMPLEMENTATION AND  TEST PLAN

 High quality  software is  easy-to-use,  accurate, robust,  understandable,  simple
 efficient.  This  list may not  be complete  (it  also may not  be minimal) but, rouj
 achievement of  these characteristics would have far  reaching impact  on EPA systj
 and  mission.

 The  ease-of-use of a system has  to  do  with the "friendliness" of  the user interJ
 Friendly Interfaces insulate the user  from many of the vagaries of the computer
 system.  Such interfaces,  which  are written in user  terminology,  reduce  the numl
 of errors committed by  the user  and make the process of  getting the  user's work
 more reliable*  A side  benefit is that  users have  less vested interest in the si
 system and are able to  change  from  computing system  to computing  system  more

 The accuracy of a system  is the  degree  to  which it satisfies its  intended requii
 Not only does an  accurate  system contain few errors, but its design  supports tl
 requirements, and  its documentation is  also accurate.  In other words, it solves
 right problem correctly.   An accurate  system embedded in a good working  environri
 makes for high reliability.

 Robustness of a system  Is  the degree to which  small changes in the requirements
 rise to small changes in  the system.  Robust systems are easy to maintain.  Robv
 is achieved primarily by designing  the  system as a model of the problem  enviror
as seen through the eyes  of  the  user.

Understandability of a  software  system  is  achieved through good documentation,
adherence to good coding standards, and programming in well-known languages.

Simplicity is a virtue  in  its own right but is Implied by the other characterist
above.

Efficiency is by  far the most abused notion on this list.  Consequently it has
 fashionable to put all efficiency considerations aside while in reality we want
 the efficiency we can afford.  In other words,  we want that amount of efficiencj
that will minimize (not lessen)  the system life cycle cost.

The Implementation and Test Plan addresses the  last five of these considerations
                                         6-1

-------
                             IMPLEMENTATION AND TEST PLAN
                                  TABLE OF CONTENTS
1.1      Overview.	 . ,
2.1      Implementation Plan . . <
2.1.1    Hardware Environment. . <
2.1.2    Software Environment. . ,
2.1.3    Implementation Strategy .
2.1.4    Configuration Control . .
2.1.5    Change Control	
2.1.6    Schedule	,
2.1.7    Resource Utilization. . .
2.1.8    Reporting	<
2.2      Test Plan 	
2.2.1    Testing Overview	
2.2.2    Types of Failures . . . .
2.2.2.1  System Design Failures. .
2.2.2.2  Detailed Design Failures.
2.2.2.3  Program Failures. . . * .
2.2.2.4  System Failures	
2.2.2.5  Performance Failures. . ,
6-3
6-3
6-3
6-3
6-3
6-3
6-3
6-3
6-3
6-4
6-4
6-4
6-4
6-4
6-4
6-4
6-5
6-5
                                         6-2

-------
                                             IMPLEMENTATION AND TEST  PLAN
f
               1.1
           OVERVIEW
               The purpose of  this document is to describe  those implementation and testing efforts
               designed to result in high-quality software.

               2.1       IMPLEMENTATION PLAN

               2.1.1     Hardware Environment

               In this section include a description of the hardware that is available for the
               implementation  of this system.
               2.1.2
          Software Environment
               In this section, describe any software tools that will be used such as pre-processors,
               library systems, code analyzers, test data generators.  Also state language selections
               and data base management systems.
               2.1.3
          Implementation Strategy
               Describe the implementation strategy, "Will the system be developed 'bottom-up* with
               lower level conponents being combined to form higher-level components?  Will it be
               developed 'top-down* with high level components being expanded in terms of lower-
               level components?  Will the system be developed in versions with an ever-increasing
               set of implemented features or will only the final version be delivered?"
               2.1.4
          Configuration Control
               Describe procedures for ensuring that completed components are "frozen" and protected
               from future change.
               2.1.5
          Change Control
               Describe change control procedures.  These procedures should allow for two kinds of
               changes.  Those that originate from the user in the form of changed requirements and
               those that originate during the implementation in the form of errors or weaknesses
               in the detailed design.  These procedures should contain provisions for decision-
               making and record keeping that are associated with these changes.
               2.1.6
          Schedule
               Include in this section a list of all components (modules, programs) of the system
               as defined by the detailed design in the order that they must be completed.  Include
               resource estimates for both the implementation and testing of each component, including
               the system testing that goes with each delivered version.
               2.1.7
          Resource Utilization
Present estimates of computing resources required along with procedures for controlling
computing resource usage.
                                                        6-3

-------
f
        2.1.8    Reporting

        Progress reporting procedures  will  be  described  in this section including  chart
        formats, rules  for declaring components  complete and  reporting  frequency.   Progress
        should only be  reported  in terms  of  completed  activities.
        2.2
TEST PLAN
        2.2.1    Testing Overview

        The ultimate objective of any  testing process during  Implementation is to attain a
        certain level of confidence that  the subject of the test is performing according to
        specifications.  We reach this objective  by designing a set of test procedures that
        will demonstrate the existance of errors.  Note that we do not try to find all errors
        in a program or system (that being much like trying to catch the last fish in a lake
        without knowing how many fish  there are or how good our bait is); rather, we try to
        find those errors which are most likely to occur or which would be most costly should
        they occur.

        In light of the above comments, this section should describe the overall testing
        strategy for this system as well as which kinds of errors are most important to
        detect for this system.

        2.2.2    Types of Failures

        A system may fail (i.e., not satisfy user requirements) in the following ways:

                 •  The System Design  (Functional Description, Draft User Guide,  Data
                    Dictionary) does not accurately reflect requirements.

                 •  The Detailed Design is not a faithful elaboration of the System Design.
                    (Frequently referred to as a specification error.)

                 •  A program within the system falls to meet its specifications.  This
                    failure can occur in two ways:  (1) Wrong operations are performed on
                    program path;  (2) The path taken is the wrong one for some data.

                 •  The performance (response time, turn around time,  etc.) of the system
                    may not be as specified.

                 •  The system design may not be implementable in the chosen environment.

        This section should Indicate those types of failures considered applicable and the
        following subsections should discuss the steps taken to detect these errors.

        2.2.2.1  System Design Failures

        The conformance of the System Design to the requirements will have  been certified by
        a  design review prior to the beginning of Detail Design.   This section should discuss
        the findings of this design review in terms of the robustness  and simplicity  of this
        system.
                                                 6-4

-------
 f
2.2.2.2  Detailed Design  Failures

The Detailed Design can best be shown  to  be a  faithful representation of the System
Design by a technical review team made up primarily of data processing personnel.
This section will describe procedures  for performing that review and will dictate the
makeup of the team.

2.2.2.3  Program Failures

Of the two kinds of program failures mentioned above, the first kind is best detected
through the use of "coverage" tests which ensure that each statement of the program
has been executed and the result observed  (either explicitly or implicitly).  Failures
of the second kind are best detected through a formal review of the subject code by
disinterested programmers (also ensuring  adherence to coding guidelines).

This section should, therefore, describe  all applicable test cases (Including how
to run them, their expected results, and  procedures to follow should they fail) and
describe the findings of the code review.

2.2.2.4  System Failures

This section will describe procedures  for  conducting the system test.  It will consist
of three parts:  (1) a review of the user  documentation to ensure that it faithfully
represents the System Design and the Detailed Design;  (2) a re-run of all program tests
on the completed systen or version; and (3) a set of randomly selected tests to
determine if there has been a gross misunderstanding of the problem.   All test cases
will be developed from user documentation and will be documented prior to running
with the expected results.  There must be  a system test for every delivered version.

2.2.2.5  Performance Failures

This section will describe procedures for doing a volume test to determine timings
and to estimate operational costs.
9
                                                       6-5

-------
                  7.    PROGRAMMER'S MAINTENANCE MANUAL
                  The  Programmer's Maintenance Manual  Is  produced  during the Implementation
                  Phase.   This document  is  intended for use  by analysts  and programmers  when
                  performing maintenance or enhancement activities in order to increase  their
                  understanding of the subject program.   Even when programs are written  according
                  to current standards,  a well written maintenance manual will invariably
                  decrease the amount of time  required to understand  both the  program and its
                  role within the system.
f
                                                      7-1

-------
                                           PROGRAMMER'S   MAINTENANCE MANUAL
      vl
I
                              TABLE OF CONTENTS

                                                                       Page

Section 1 - Introduction	7-4

1.1       Summary Overview  	  7-4
1.2       History	7-4
1.3       Environment	7-4
1.4       Document Organization	7-4



Section 2 - System Overview	  7-5

2.1       Application	7-5
2.2       Requirements	7-5
2.3       Software Functions 	  7-5
2.4       program Hierarchy  	  7-5
2.5       Inputs	7-5
2.6       Processing	7-5
2.7       Outputs	7-5
2.8       Interfaces	7-6



Section 3 - Program Descriptions	7-7

3.1       Identification of Program 1	7-7
3.1.1     Software Function  	  7-7
3.1.2     Inputs	7-7
3.1.3     Processing	  7-7
3.1.4     Outputs	7-8
3.1.5     Interface Requirements 	  7-8
3.1.6     Data Description	7-8
3.1.7     Program Execution Requirements 	 ..........  7-8
3.2       Identification of Program 2	7-8
  •
  •


Section 4 - System Environment ...  	 ..........  7-9

4.1       Hardware Configuration	  7-9
4.2       Software Configuration 	  7-9
4.3       Data Base Requirements	  7-9
                                                          7-2

-------
                                            TABLE OF CONTENTS (Cont'd)
Section 5
5. 1
5.2
5.3
5.4
5.5
5.6







Page
	 7-10
	 7-10
	 7-10
	 7-10
	 7-11
	 7-11
	 7-11
                  Appendixes	7-12
                  Appendix A - Project  References
7-13
                  Appendix  B  - Glossary	7-14
I
                                                       7-3

-------
I
                                 PROGRAMMER ' S   MAI NTENANCE MANUAL
                                      SECTION 1 - INTRODUCTION
           1.1        SUMMARY OVERVIEW

           This  subsection introduces the reader to the software system described in
           this  manual.   The general nature and application of the  processing performed
           by the  software to be maintained are presented.   Any security or  privacy
           requirements  are included in this subsection.
           1.2        HISTORY

           This  subsection presents the history of the development  of  the  software
           system.   All  major  events are summarized and the  applicable  reference material
           is identified and discussed, Including all  significant source documents.
           (All  references will  be  identified  in Appendix  A,  Project References.)
           1.3        ENVIRONMENT

           This  subsection  identifies  the  environment  of  software described  in  this
           document.   Items such as  the  following are  included:

                     •   Program sponsor

                     •   Software developer

                     •   Computer center  or  network where  software  Is  implemented

                     •   Normal user(s).


           1.4        DOCUMENT  ORGANIZATION

           This  subsection  presents  the  purpose  of the  Program Maintenance Manual, the
           intended users,  and a summary statement on  the contents of each section
           of the manual.
                                                7-4

-------

                                                    SECTION  2 - SYSTEM OVERVIEW
                           2.1
APPLICATION
                           This subsection describes  the purpose of the software system and the funetioj
                           it performs.  This description is presented in terms of user-oriented
                           requirements as opposed to software functions performed within the system.
                           2.2
REQUIREMENTS
                           This subsection lists all the user requirements fulfilled by the software
                           system.  Requirements are related to programs in order to aid the individual
                           making modifications in relating the program structure to specific requiremet|
                           (see the following subsections).
                           2.3
SOFTWARE FUNCTIONS
                           This subsection summarizes all software functions and relates the software
                           functions to the requirements fulfilled by the software system.
                           2.4
PROGRAM HIERARCHY
                           This subsection presents a top-down structure of the software system and
                           relates each software function to the individual program(s) satisfying the
                           software function.
                           2.5
INPUTS
                           This subsection lists all software inputs and provides a summary description
                           of the inputs, including examples, formats, or references to other documents
                           for details about the input.
                           2.6
PROCESSING
                           This subsection summarizes all processing performed by the software system
                           and relates all inputs and outputs to the given process.
                           2.7
OUTPUTS
                           This subsection lists all software outputs and provides a summary description |
                           of the outputs, including examples, formats,  or references to other  documents
                           for details about the output.
It
                           7-5

-------
                                                                                                          1
2.8
                     INTERFACES
          This  subsection describes all interfaces  with other  software
          lists references for additional information  about  each l-r ••<•••
                                                                   :•!.  -rl.l
I
                                                7-6

-------
                       SECTION 3 - PROGRAM DESCRIPTION
3.1
IDENTIFICATION OF PROGRAM 1
This subsection identifies the program by name, tag or label, and programming
language.  A version number of the program is also included as appropriate.
3.1.1
Software Function
This subsection identifies the software function(s) performed by this program.I
A description of the problem and corresponding solution is given.  The solutio|
is given in terms of the methods used within the program.

3.1.2     Inputs

This subsection describes in detail the Inputs used by this program and includj

          •    All data used by the program during its execution

          •    Data types and location(s) required to begin progr.-ni e«.>.Mr? .

          •    All entry requirements concerning program initii'  ' > ••

3.1.3     Processing

This subsection describes all processing performed on the input listed in
Section 3.1.2.  The description of the processing includes:

          •    Description of each major operation of the program

          •    Major branching or decision points within the program flow

          •    Constraints or limitations on the processing

          •    Program exit requirements for terminating execution

          •    Transition to the next program element

          •    Error processing

          •    Output media and types

          •    Storage requirement

          •    Execution time requirements.
                                     7-7

-------
I
           3.1.4     Outputs

           This subsection describes in detail all outputs produced by this program and
           includes:

                     •    All data modified by this program during execution

                     •    All additional data generated

                     •    Data types and location(s) resulting from program execution.


           3.1.5     Interface Requirements

           This subsection describes all interface requirements to execute this program
           if it is not a stand-alone program, including other programs,  special test
           drivers, and data generators, etc.


           3.1.6     Data Description

           This subsection describes all data items used within the program,  including
           data arrays, tables,  COMMON locations,  temporary work areas  and buffers,  etc.
           The following will be provided for each data item:

                     •    Tag, label, or symbolic  name

                     •    Purpose of data item

                     *    Other  programs that use  data item

                     •    Logical divisions within data

                     •    Basic  data structure.


           3.1.7     Program Execution Requirements

           This subsection summarizes the operating procedures to run the  program,
           including compiling,  loading, operating, terminating,  and error handling.
           Any unique run features not Included  in the Operations Manual are  included in
           this subsection.


           3.2       IDENTIFICATION OF PROGRAM 2

           A subsection, as described above, Is  provided for each program  within the
           system.
                                                7-8

-------
I
                                          SECTION  4  -SYSTEM ENVIRONMENT


                 4.1       HARDWARE CONFIGURATION

                 This subsection provides a description of the equipment required for operating
                 the system.  The hardware requirements are related to each program described
                 in Section 3, and include the following items:

                           •    Internal storage  required for processor

                           •    On-line or off-line storage, media, form, and devices

                           •    Input and output  devices, both on-line and off-line

                           •    Data communications devices.

                 A hardware diagram will also be  included.

                 4.2       SOFTWARE CONFIGURATION

                 This subsection provides a description of all support software required for
                 the execution of each program.  Areas covered are as follows:

                           •    Operating System - Identification, version or release,  and any
                                unusual features used for each program

                           •    Compiler/Assembler - Identification, version or release, and
                                any unusual features used for each program

                           •    Other Software - Identification of any other support  software
                                used, including data base management systems,  utilities,
                                macros, report generators, etc.

                 4.3       DATA BASE REQUIREMENTS

                 This subsection provides a description of each data base,  file,  table,  or
                 data dictionary used by each program.   The following information will  be
                 Included:

                           •    Format

                           •    Units of measurement

                           •    Codes

                           •    Range of values

                 If the  information required  is extensive,  a  reference may  be  used for  details
                 about each data base,  file,  table or  data dictionary  used  by  the program.
7-9

-------
                            SECTION 5 - MAINTENANCE TOOLS AND PROCEDURES
           5.1       CONFIGURATION CONTROL AND MANAGEMENT

           This subsection presents all formal procedures to be followed in making
           modifications to the system, including all applicable forms and documentation.

           5.2       PROGRAMMING CONVENTIONS

           This subsection summarizes and/or references all applicable programming
           conventions used in developing the software system.  Items Included are

                     •    Coding conventions

                     •    Documentation within the code, such as prologs and inline comments

                     •    Design scheme for mnemonic identifiers and labels

                     •    All sumbols and conventions used In preparing the code, such as
                          charts, listings, serialization of cards, abbreviations used
                          in statements and remarks, etc.

           5.3       DOCUMENTATION CONVENTIONS

           This subsection will contain, or provide a reference to, the location of the
           program listings.  All documentation conventions used within the listings to
           describe the code will be explained or reference will be made to the appropriate
           software standards document.  An example will be Included if applicable.  All
           programs will have two levels of comments:  one in the form of a prolog and
           the other as inline comments.  These levels are summarized below:

                     •    Prolog - The prolog will contain as a minimum (1) the program
                          name, EPA organization responsible for the program, author's
                          name, and name of the system of which the program is part;
                          (2) the relationship of the program to other programs, files,
                          and control cards; (3) a description of all principal symbolic
                          names used in the program, including the meaning of different
                          values of switches, etc.; and (4) a description of the overall
                          logic of the program, Including method of solution used.

                     •    Inline comments - The comments, located throughout the program
                          at major sections, shall contain (1) -a description of the logic
                          of the section in more detail than given in the system-level
                          comments, including the symbolic names affected; (2) a state-
                          ment as to which conditions cause the section to be entered;
                          and (3) a statement as to which section or subsections follow
                          the execution of this section.
I
                                                 7-10

-------
 f
                  5.4       TEST TOOLS  AND PROCEDURES

                  This subsection describes all test tools and procedures  used  to verify the
                  execution of  the program at the unit level.   This  information includes:

                            •    Test procedures and expected  results

                            •    A description of required test data,  test  drivers,  simulators,
                                 etc.,  including test data ranges, limits,  and  error conditions
                                 for  each

                            •    A description of all test tools available, including special
                                 options such as debug statements and  dumps,  execution counters,
                                 timing devices, etc.

                  5.5       ERROR PROCEDURES

                  This subsection describes all error conditions, including identification of
                  the error, explanation of the source,  and recommended methods  to correct the
                  error.   Each  error  will  be related to  the program(s) in which  it can occur.

                  5.6       SPECIAL MAINTENANCE PROCEDURES

                  This subsection contains an inventory  and description of  any  special programs
                  used to maintain the  system and all related  maintenance procedures.   Procedures
                  include requirements, processing,  and  verification necessary  to naintaln
                  system  input/output components, such as  data base and system  library support.
I
                                                       7-11

-------
                                                APPENDIXES
•-*
These sections contain supporting information and lists which for the sake of
convenience and readability are left out of the main sections of this document.
The two described here (Project References and Glossary) are required.  Additional
appendixes may be added as appropriate.  The order in which the appendixes
occur is incidential.
                                                   7-12

-------
                                          APPENDIX A - PROJECT REFERENCES


                   This appendix contains a summary of related pertinent documents or monographs.
                   Examples are:

                             •    Operating system reference  manuals

                             •    System processor reference  manuals  (e.g.,  Text  Editor)

                             •    Requirements documents

                             •    Mission definition documents.
I
7-13

-------
                                              APPENDIX B - GLOSSARY
                  The glossary is an alphabetic list of special terms, initials, and acronyms
                  (and their definitions) that are used in this document.
I
7-14

-------
                          8.
          CODING GUIDELINES
                          8.1
          INTRODUCTION
 c
The source code is one of the most important forms of documentation for any
system or program; the quality of that code can depend, to a large extent,
on the time and effort spent during the preceding phases of system or program I
development.  Since other types of documentation used for software maintenanc^
(such as programmer's manuals) are frequently out of date within six months
of their release, the source code, which is usually current, can enjoy undue
prominence.  The relative excellence, however, of important coding character-l
istics - such as efficiency; freedom from errors; and the degree of difficulty
posed by maintenance, modification, and/or enhancement - can be traced, at
least in part, to earlier stages in software development, and in particular
to the design stages.  In turn, good documentation of the earlier phases
provides a valuable historical record of the software design that may facilit^
the debugging, maintenance, modification, or enhancement of the program or
system.  Each successive phase of software development should be thought of
as part of an ongoing process contingent upon the preceding phases, and not
as a discrete set of problems, choices, and decisions confronted and resolved|
without regard to the previous and subsequent phases.  In short, careful
development and review of software design should result in source code that
is efficient, free of errors, easy to maintain, and flexible enough to be
compatible with any future modifications or enhancements.

The principal beneficiaries of software documentation are the software
maintenance personnel.  The maintenance programmer relies heavily on the
source code for the most accurate, detailed information about the software.
Consequently, it is not sufficient for the source code listings to be simply
a list of the source statements.  If all necessary information is in the code]
itself and if the code is readable, maintenance and modification become much
easier.  A well-written, intelligible, and readable program is usually more
reliable and free of errors.  The gross inefficiencies and errors inherent inj
sloppy, confused logic are eliminated.  The logical structure of a readable
program is apparent, which facilitates the recognition of inefficient code
and the detection of errors.

This standard is intended to provide suggestions and guidelines for developir
source code of good quality that will serve as an effective documentation forj
                         8.2
          CHOICE OF LANGUAGE
                         The selection of a source language is usually either made by the system
                         designer or Imposed by the user.  Whoever makes the selection should choose
                         the language that is best able to express the functions of the problem in
                         terms which lead to efficient machine execution.  The greatest Influence on
                         machine execution is program design.  If an efficient design has been
                         formulated, the language used for coding is usually of secondary importance.
I
                                     8-1

-------
           High-level languages are  preferred  over assembly language code  (ALC).  Programs
           written in high-level languages are generally easier  to debug,  maintain, and
           modify.  They contain logical and control structures  that facilitate programming.
           With respect to source code as a documentation  form,  they are more readable.
           The current tools available for analyzing and optimizing source code have
           relegated the use of assembly languages to extreme situations.  Assembly
           language should only be used for utilities which provide operating system or
           hardware interfaces that  are unavailable In high-level languages.
I
           8.3       PROGRAMMING STYLE

           8.3.1     What is Style?

           Style is typically defined as a characteristic or distinctive form of expressing
           thought in writing or speaking which Is often considered exemplary in nature.
           This definition holds equally well for programming - the coding phase of a
           project should be nothing more than writing a previously defined algorithm in
           some programming language.

           The most important result of good style Is program readability.  Since most
           production programs are read by considerably more people than write them,
           program readability and understandabillty are of primary importance.  Program
           readability also becomes of paramount importance when one considers that
           program source listings are usually the best technical documentation available
           to the maintenance programmer.

           Although programming style will vary from programmer to programmer, the basic
           components of all good styles are:

                     •    Good program constructs

                     •    Consistent language usage

                     •    Use of meaningful mnemonics

                     •    Good comments.

           It is considered good programming practice to use the simplest, most straight-
           forward coding possible, even if this Is not the most efficient coding from a
           hardware point of view.

           If efficiency becomes a major concern, a program evaluator should be used
           after the program is debugged and working.  The relevant areas of code should
           then be optimized, comparing the results with the original, working version.
           The use of short cuts or reliance on the side effects of instructions should
           be avoided.  Similarly, clever or tricky coding is shunned by these guidelines
           because it obscures processing, causes problems in maintenance, and can
           create hard-to-detect side effects.  Writing a simple, straightforward,
           understandable program is an Intellectual and creative challenge.  Although
           initially more difficult than the alternative, it will result in easier debugging
           and maintenance and greater reliability.
8-2

-------
                  8.3.2
 f
          Good Program Constructs
                  Good program constructs are largely a result of sound initial design and
                  consist of graphically presenting a program in a form similar to that of the
                  design.  This includes effective use of modularization and appropriate
                  indenting of source code.  For example, at the beginning of a program,

                            PERFORM INITIALIZE.
                            PERFORM PROCESS-RECS UNTIL END-OF-INPUT.
                            PERFORM CLEANUP.

                  is far more readable than
                            OPEN INPUT FILE-IN.
                            OPEN OUTPUT FILE-OUT.
                            MOVE 0 TO RECS-IN RECS-OUT.
                            READ FILE-IN AT END GO TO DONE.
LOOP.
                            .     record processing
                            *
                            GO TO LOOP.
                  DONE.
                  Acceptable program constructs are discussed further in Section 8.5.4.
8.3.3
Consistent Language Usage
                  Consistent language usage calls for coding similar tasks in a similar  manner.
                  Doing so not only eases the burden of the maintenance programmer,  but  also
                  improves the reader's ability to understand the intent of a piece  of code.
                  For  example, the use of binary integers for all counters underscores the  use
                  of  these items as counters better than if some were character strings.
                  Use  of dissimilar approaches to similar problems in the same program is
                  frequently an indication that the original programmer may not have fully
                  understood what he was doing.
                  8.3.4
          Use of Meaningful Mnemonics
                  Use  of meaningful  mnemonics for item names cannot  be  overemphasized.   It  is
                  sufficient  to note that INPUT-REC-COUNT is far  superior  to CNT1  and  that
                  PROCESS-ERROR is clearer than OOPS.
I
                  8.3.5
          Good Commenting
                  Good  commenting  is  absolutely necessary if the time  spent  by the maintenance
                  programmer  in understanding a program is to be minimized.   Program comments
                  (in particular the  Prolog) should correctly state  the  intent of a block of
                  code,  thereby simplifying the debugging process If errors  exist in the code.
                                     8-3

-------
I
           Good comments describe what  is  being  done  in a  block of  code  -  not  how  a
           block of code works.  If  the programmer  feels it  necessary  to describe how a
           block of code works, the  code in  question  is unnecessarily  complicated,
           long, and/or obscure.
                                                                        Comments  on  every
Good commenting implies quality, not quantity, of comments.
line of code detract from program readability.

8.4       PROGRAM LAYOUT

8.4.1     Prologs

A prolog is a block of comments that precedes a unit of source code.  It
contains essential information for debugging, maintenance, and modification
and greatly facilitates these activities.  Having this information easily
accessible in the source code is much more useful than having it scattered
among isolated notes, manuals, and other individuals.  Writing a prolog before
starting to code helps clarify program requirements for the programmer.  When
programming is finished, the prolog must be checked for accuracy, since it is
one form of the final documentation of the program.  Because other programmers
will use the prolog for interface information, it should be checked and
updated each time the routine is compiled.

A full prolog, as illustrated in Figure 1, should be included for every
software unit capable of being separately compiled.  An abbreviated form can
be used for internal subroutines.  An outline of a prolog is presented below.
A blank line (beginning with the comment character) separates each item.  The
items in a prolog are as follows:

          1.   IDENTIFICATION LINE - This line indicates the name of the program
               to which the routine belongs and possibly an index or version
               number.

          2.   ENGLISH NAME - The English name of the routine should be
               indicated.

          3.   LANGUAGE USED - The computer model, compiler or assembler version
               (number), and operating system version or level number should
               be noted.

          4.   PURPOSE OF ROUTINE - Describes the net effect of one execution
               of the code, not an explanation of how the routine accomplishes
               its effect*  A routine should have one purpose.

          5.   CALLING SEQUENCE - Formal arguments or other linkage should be
               described.

          6.   NOTES - These include restrictions, requirements,  and references.
               A description of access conditions or execution environment
               should be provided.
                                     8-4

-------
 f
                      LANGUAGE:   UNIVAC 1108 FORTRAN V VERSION E3.   EXEC8 LEVEL 33.

                      PURPOSE: DETERMINE DENSITY AND NUMBER OF TRACKS  FOR A MAGNETIC TAPE
                              ASSIGNMENT.

                      CALLING SEQUENCE:
                          ARGUMENT  I/O  DESCRIPTION
                          EQCOD
                          MODSET

                          TRKS
                          DENSITY
              I
              I

              0
              0
SIX-BIT EQUIPMENT CODE FROM FITEM PACKET
EIGHTEEN LOW ORDER BITS CONTAIN THE MODE SETTINGS
FROM THE FITEM PACKET
NUMBER OF TAPE RECORDING TRACKS, BINARY
TAPE RECORDING DENSITY (FRAMES PER INCH, BINARY)
      SUBROUTINE  TAPTYP(EQCOD,  MODSET,  TRKS,  DENSTY)
C*****SUBR: TAPTYP   VERSION:  2   SAT:  SMS-GOES   PROGRAM:  VISSR ********
C
C   ENGLISH NAME: TAPE ASSIGNMENT TYPE
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
c   .
c***********************************************************************
NOTES: 1. VALID RESULTS ARE ONLY RETURNED FOR UNISERVO 12/16/20
     TAPE ASSIGNMENTS.
     2. CALLING PROGRAM OBTAINS FITEM PACKET FROM SUBROUTINE UFITEM.
     3. SEE PP. 7-8,  7-9 OF 1108 P.R.M. ON FITEM PACKET FOR
     DESCRIPTION OF EQUIPMENT CODES, MODE SETTINGS.

VARIABLES: (LOCAL)
     DMASK «= BIT MASK FOR DETERMINING DENSITY.

ERROR HANDLING: IF 'EQCOD1 DOES NOT INDICATE A UNISERVO 12/16/20
       TAPE UNIT THEN 'TRKS' AND 'DENSTY' ARE SET TO ZERO.

CALLS: NONE.

CALLED BY: TAPHND.

METHOD: TAPTYP USES THE EQUIPMENT CODE TO DISTINGUISH BETWEEN
     7 AND 9 TRACK UNITS.  USING BIT MASK DMASK, THE DENSITY IS THEN
     EXTRACTED FROM THE MODE SETTINGS.

PROGRAMMER: S. SANDERS,  CSC, NOVEMBER 1975.

MODIFIED: R. BIERI, CSC, JULY 1977.   ERROR HANDLING CHANGED.
I
                        Figure 1.  Prolog (Full Form)

                                     8-5

-------
                     7.    VARIABLES  - Information should include descriptions of variable
                          functions and indications of which variables in COMMON blocks
                          are  changed,  which variables are local, and  which are input
                          and  output.   File usage may also be described.   Calling
                          arguments are described under CALLING SEQUENCE  (item 5, above).
                          Some items to be included are:

                          a.    Itemized lists and descriptions

                          b.    Summaries (if a whole COMMON block is used,  the block
                               should  be identified)

                          c«    Lists of exceptions

                          d.    References  to the  source code location  of  the information
                               (some COMMON block listings include detailed  variable
                               descriptions; local variables might be  flagged in the code).

                          Another  programmer must be able  to easily determine the
                          function of  each variable used  in the routine.

                     8.    ERROR HANDLING - The types of errors  that are detected and
                          how  they are  handled should be  noted.   If no checking is
                          performed, "None" should be indicated.

                     9.    CALLS -  Required subroutines  (or entry points to large utilities)
                          should be listed.   If no subroutines  are required,  "None"
                          should be Indicated.

                   10.    CALLED BY - Routines  which call  this  routine should be listed.
                          Most  routines  are called by only one  or two  other routines.
                          If this  is a  utility (called  by  many  other routines),  "Utility"
                          should be indicated.

                   11.    METHOD - The  specific software operations that are  used to
                          accomplish the purpose  of  the routine should be Indicated.
                          A short  general  description should  be  given.  The method
                          description,  along with the comments  in the  code, should allow
                          another  programmer to easily  understand the  processing algorithm.
                          Program  design language (PDL) could be  substituted  for narrative.

                   12.    PROGRAMMER AND DATE - The  programmer  or analyst, location,
                          and  date (month/year) should  be  noted.

                   13.    MODIFIED  - This  section,  used to list  important changes,
                          should include references  to  change control  procedures and
                          the  programmer's  name.
I
8-6

-------
f
A bound set of prologs can make up most of  the detailed design and program
documentation for a system.  By putting this information in the code where
it is most useful, much of the detailed material in formally published
documents can be eliminated.  Documentation costs are substantially reduced,
and the published documentation, which contains only high-level descriptions,
is less subject to change.
                 8.4.2
          Annotation
                 Annotating code is not a simple process.  The objective is to give enough
                 information so that another programmer can understand the routine and at the
                 same time avoid unnecessary comments.  The nature of high-level languages is
                 that they are descriptive of the very processes they perform.  However, they
                 are frequently inadequate to describe what is accomplished by the process.
                 It is in this context that comments can be used most effectively - to supply
                 meaning to source code when the source language falls short.
                 8.4.3
          Blocking of Statements
                 High-level languages, while being more readable than assembly language, are
                 not so readable as to be self-documenting.

                 However, the technique of blocking source code statements can improve the
                 readability of high-level languages (see Figures 2, 3, and 4) by approximating
                 paragraphs.  A block is a group of related statements which perform a specific
                 function.  Within these guidelines, subroutines must be divided into blocks of
                 related statements.  Examples of large blocks would be initialization,
                 input/output, error processing, or alternative processing sections.  Smaller
                 blocks within these sections might be loops, a few arithmetic statements
                 which make a single computation, or a conditional statement with its alternative
                 groups of instructions.  If these groups are large enough, they might become
                 smaller blocks within the conditional block.  Examples of blocks are presented
                 in Figures 3 and 4.

                 Monolithic program listings do not group statements into blocks and do not
                 set the blocks apart with blank comment lines, indentation, or other techniques
                 described in this section.  Such undivided listings are difficult to read (see
                 Figure 2).  The smallest blocks in a routine should be set off with a blank
                 comment line before and after; larger blocks can be set off with a number of
                 blank lines and prominent comments or headers (see Figure 3).

                 A block of any size should have only one purpose.   A few lines of code should
                 be duplicated (copied in line where they will be sequentially executed) if
                 this will bring together all statements related to one function.  The use of
                 GO TOs or jumps to pick up several isolated statements (to avoid copying them
                 in line) leads to logic errors and creates confusion (see Figure 5).

                 A block should have only one entry point (at the top) and one exit point (at
                 the bottom), with the exception of error and loop exits.
 I
                                     8-7

-------
t
           IF PWS-NORMAL-CAPACITY - '$         •
           MOVE DEFAULT-ACTION TO BLD-INV-ACT
           MOVE 0 TO BLD-C186
           ELSE IF PWS-NORMAL-CAPACITY NOT *• SPACES
           MOVE DEFAULT-ACTION TO BLD-INV-ACT
           MOVE PWS-NORMAL-CAPACITY TO BLD-C186;
           IF PWS-DESIGN-CAPACITY - '$         '
           MOVE DEFAULT-ACTION TO BLD-INV-ACT
           MOVE 0 TO BLD-C187
           ELSE IF PWS-DESIGN-CAPACITY NOT = SPACES
           MOVE DEFAULT-ACTION TO BLD-INV-ACT
           MOVE PWS-DESIGN-CAPACITY TO BLD-C187.
           IF PWS-EMER-POWER - $           '
           MOVE DEFAULT-ACTION TO BLD-INV-ACT
           MOVE 0 TO BLD-C188
           ELSE IF PWS-EMER-POWER NOT  = SPACES
           MOVE DEFAULT-ACTION TO BLD-INV-ACT
           MOVE PWS-EMER-POWER TO BLD-C188.
           IF PWS-S TOR-CAPACITY  - '$          '
           MOVE DEFAULT-ACTION TO BLD-INV-ACT
           MOVE 0 TO BLD-C189
           ELSE IF PWS-S  TOR-CAPACITY  NOT  -  SPACES
           MOVE DEFAULT-ACTION TO BLD-INV-ACT
           MOVE PWS-S TOR-CAPACITY TO  BLD-C189.
           IF PWS-MAX-PROD = '$          '
           MOVE DEFAULT-ACTION TO BLD-INV-ACT
           MOVE 0 TO BLD-C190
           ELSE IF PWS-MAX-PROD NOT -  SPACES
           MOVE DEFAULT-ACTION TO BLD-INV-ACT
           MOVE PWS-MAX-PROD TO BLD-C190.
Figure 2.  Uneeparated Code
            8-8

-------
                 * Update PWS-NORMAL-CAPACITY (C186 in database)
                 *
                      IF   (PWS-NORMAL-CAPACITY - '$         ')
                           MOVE DEFAULT-ACTION TO BLD-INV-ACT
                           MOVE 0              TO BLD-C186

                      ELSE IF (PWS-NORMAL-CAPACITY NOT - SPACES)
                              MOVE DEFAULT-ACTION      TO BLD-INV-ACT
                              MOVE PWS-NORMAL-CAPACITY TO BLD-C186.
                 *
                 * Update PWS-DESIGN-CAPACITY (C187 in database)
                 *
                      IF   (PWS-DESIGN-CAPACITY - '$         ')
                           MOVE DEFAULT-ACTION TO BLD-INV-ACT
                           MOVE 0              TO BLD-CI87
                      ELSE IF (PWS-DESIGN-CAPACITY NOT = SPACES)
                              MOVE DEFAULT-ACTION      TO BLD-INV-ACT
                              MOVE PWS-DESIGN-CAPACITY TO BLD-C187.
                 *
                 * Update PWS-EMER-POWER (C188 in database)
                 *
                      IF   (PWS-EMER-POWER - f$         ')
                           MOVE DEFAULT-ACTION TO BLD-INV-ACT
                           MOVE 0              TO BLD-C188
                      ELSE IF (PWS-EMER-POWER NOT - SPACES)
                              MOVE DEFAULT-ACTION TO BLD-INV-ACT
                              MOVE PWS-EMER-POWER TO BLD-C188.

                 * Update PWS-STOR-CAPACITY (C189 in database)

                      IF   (PWS-STOR-CAPACITY = '$         ')
                           MOVE DEFAULT-ACTION TO BLD-INV-ACT
                           MOVE 0              TO BLD-C189
                      ELSE IF (PWS-STOR-CAPACITY NOT = SPACES)
                              MOVE DEFAULT-ACTION    TO BLD-INV-ACT
                              MOVE PWS-STOR-CAPACITY TO BLD-C189.
                 *
                 * Update PWS-MAX-PROD (Cl»0 in database)
                 *
                      IF   (PWS-MAX-PROD - '$         ')
                           MOVE DEFAULT-ACTION TO BLD-INV-ACT
                           MOVE 0              TO BLD-C150
                      ELSE IF (PWS-MAX-PROD NOT « SPACES)
                              MOVE DEFAULT-ACTION TO BLD-INV-ACT
                              MOVE PWS-MAX-PROD   TO BLD-C190.
t
Figure 3*  Code Divided Into Blocks and Separated  by  Headers

                            8-9

-------
I
                  c
                  c
                  c
                  c

                  1002

                  C
                  C

                  C
                  C
                  c
                  c
                 c
                 c
                 c
                 c
                 c
                 c
 SETUP BEGIN AND END POINTER
 IB=ISTART
 IE=IEND

 SEARCH FOR IDP BETWEEN TABLE (IB),...,  TABLE (IE)

 INDEXP-IB
 IF  (IDP .EQ.  IPLANT(IB)) RETURN

 IDP FALLS IN FRONT OF  IPLANT (IB),  INSERT IDP INTO IPLANT.
 IF  (IDP .LT.  IPLANT(IB)) GO TO 1099

 IDP FALLS BEHIND  IPLANT (IB)

 IF  IB IS  THE  SAME  AS IE,  INSERT IDP.
 IF  (IB .EQ.  IE) THEN
    INDEXP=IE+1
    GO TO  1099
 END IF

 IB  AND IE ARE  ADJACENT TO EACH  OTHER
 IB1=IB+1
 IF  (IB1 .EQ. IE) THEN
    INDEXP=IE
    IF  (IDP .EQ. IPLANT(IE)) RETURN
    IF  (IDP .LT. IPLANT(IE)) GO  TO  1099
    INDEXP-IE+1
    GO  TO  1099
END  IF

OTHERWISE, DETERMINE THE MIDDLE POINT OF IB and IE.
IMID=(IB+IE)/2.
IF  (IDP .EQ. IPLANT(IMID)) THEN
    INDEXP^IMID
   RETURN
END  IF

IDP FALLS INTO UPPER HALF OF THE TABLE,  RESET IE AND SEARCH AGAIN.
IF  (IDP .LT. IPLANT(IMID)) THEN
   IE=IMID
   GO TO 1002
END IF
                 C      IDP FALLS INTO LOWER HALF OF THE TABLE, RESET IB AND SEARCH AGAIN.
                        IF (IDP .GT. IPLANT(IMID)) THEN
                           IB=IMID
                           GO TO 1002
                        END IF
                 1099 CONTINUE
                                     Figure 4.  Code Separated Into Blocks

                                                      8-10

-------
                            poor  usage to  avoid  code  duplication:

                                 IF(FIRST  .EQ. 1)GO TO 20
                            10   ...  block A
                                 IF(FIRST  .EQ. 1)GO TO 30
                            20   ...  block B
                                 IF(FIRST  .EQ. 1)GO TO 10
                            30   ...  block c
                                 FIRST=0
L
                           duplication  improves  understanding

                                 IFCFIRST  .EQ.  1)GO TO 10
                                 ... block A
                                 ... block B
                                 GO TO 20
                           10    ... copy  of block B
                                 ... copy  of block A
                                 FIRST=0
                           20    ... block C
                                             Figure 5.   Poor  Usage  -  Copy Lines of Code

                                                                8-11

-------
                 8.4.4
          Format
£  1
As discussed  in  the  previous  subsection, routines  consist  of  blocks  of  related
statements that  are  linked  together  in  some  logical way.   Figures  6  and 7
illustrate the techniques of  blocking combined  with indentation.

Horizontal indentation  is most useful for  languages like FORTRAN.  Statements
or comments on the same logical  level must be evenly  indented.  A  consistent
number of spaces should be  used, either four or five  for each level.  This
enables programmers  to  determine which  statements  are within  the range  of a
loop.  Debugging statements or logically subordinate  statements can  be  further
indented from more important  code.   Comments (other than inline) should precede
the code they describe  and  be indented  to  the right of the code.   Exceptions
would be headers or  very important comments, which should  be  set off with a
border or with leading  asterisks or  other  characters.  It  should be  easy
to distinguish the executable instructions from the comments  (Figures 6 and 7).

If code is indented  to  show logic structure  (whether  by the programmer  or by
structured programming  macros),  the  indentation must  be consistent.  Assembly
language code must also be  separated vertically into  blocks.

Part of the art  of programming lies  in  the aesthetics of a clean program
listing.  Although a clean  layout does not guarantee a correct program, a
program with  a clean, readable format is more often correct than one with a
messy, confusing format  (Figure  8).

8.5       CODING PRACTICES

8.5.1     Efficiency

Efficiency, which was a major concern with second-generation hardware,  has
been the cause of more  badly written code  than any other factor.  Various
studies have  shown that  fewer than four percent of the statements in a  typical
FORTRAN program  account  for more than half of the execution time.   Worrying
about minor savings  in  individual code statements or instructions is a waste
of the programmer's  time.  The fact that execution time is critical does not
mean a program must  be  written in assembly language.  The greatest influence
on execution  time is program design.   If an efficient design has been
formulated, the  language used for coding is of secondary importance.   If a
higher level  language is used for its readability and programming efficiency
and the program  written  in  this language executes fast enough, the problem is
solved.   If the object  program is too slow, the bottlenecks can be located and
improved.  If the original design is inefficient, however,  no language will
compensate for this deficiency.

The proper method for writing an efficient program involves constructing an
efficient design and then writing a logically sound and readable program.
                                                      8-12

-------
                           S2: DO K=N TO 2 BY -1;
                           MAXV=AR(1); MP-1; DO 1=2 TO K BY 1;
                           IF AR(I)>MAXV THEN DO: MAXV=AR(I); MP»I; END;
                           END; TMP-AR(K); AR(K)=AR(MP); AR(MP)=TMP; END S2;
A.
VALEAF-SETUP.
    IF VALEAF-REC-HELD - 1 MOVE SPEC-EAF-HOLD TO VAL-EAF
    GO TO NO-READ.
    READ VALEAF AT END MOVE 1 TO EAF-EOFEOF.
NO-READ.
    MOVE 0 TO VALEAF-REC-HELD EAF-RECS-BCNT.
SAVE-LOOP.
     IF EAF-EOFEOF - 1 OR VALEAF-REC-HELD = 1 GO TO SETUPDUN.
    IF VEAF-ID < SAVE-ID MOVE VEAF-ID TO RPT-PWS
       MOVE EAF-ID TO RPT-REC
       MOVE EAF-TYPE TO RPT-TYPE
       GENERATE DETL
    ELSE GO TO NO-READ2.
   READ VALEAF AT END MOVE 1 TO EAF-EOFEOF.
   GO TO SAVE-LOOP.
NO-READ2.
   IF VEAF-ID > SAVE-ID MOVE 1 TO VALEAF-REC-HELD
      MOVE VAL-EAF TO SPEC-EAF-HOLD GO TO SAVE-LOOP.
   ADD 1 TO EAF-RECS-BCNT.
   MOVE 1 TO SUMM-EA-UPD.
   ADD 1 TO SUMM-EA-CNT.
   IF EAF-RECS-BCNT > EAF-RECS-BMAX PERFORM WRITE-EAF-EXCESS
   ELSE MOVE VAL-EAF TO VAL-EAF-BUF (EAF-RECS-BCNT).
   READ VALEAF AT END MOVE 1 TO EAF-EOFEOF.
   GO TO SAVE-LOOP.
SETUPDUN. EXIT.
                                            Figure 6.   Uncommented  Poorly Formatted  Code

                                                                8-13

-------
           /*                */
           /*  SORT  ARRAY AR */
           /*                */
              SORTAR:   DO K= -  N  TO 2 BY -1;
                       /*                                      */
                       /* FIND  GREATEST VALUE IN AR(1)...AR(M)  */
                       /*                                      */
                           MAXVAL = ARR(l);
                           MAXPOS = 1;
                           DO I - 2 TO K BY  1;
                               IF AR(I) > MAXVAL THEN DO;  MAXVAL  -  AR(I)
                                                          MAXPOS  -  I;
                                                      END;
                           END;
                           /*                                             */
                           /* MOVE  GREATEST VALUE TO  END OF AR(1)...AR(M)  */
                           /*                                             */
                           TEMP       - AR(K);
                           AR(K)       - AR(MAXPOS);
                           AR(MAXPOS)  - TEMP;
                      END SORTAR;
t
Figure 7a.  Well-Formatted and Commented Code

                     8-14

-------
                  VALEAF-SETUP SECTION.
                  SECT-ENTRY.
                      IF VALEAF-REC-AVAILBL
                                            MOVE SPEC-EAF-HOLD TO VAL-EAF
                      ELSE
                                            PERFORM READ-NEXT-VALEAF.
                      MOVE  0 TO VALEAF-REC-AVAILBL-INDIC.
                      MOVE  0 TO EAF-RECS-BCNT.
                      PERFORM SAVE-VALEAF-RECS  UNTIL EAFEOF
                                                  OR VALEAF-REC-AVAILBL.

                   SECT-EXIT.  EXIT.
                  * THIS  SECTION SAVES THE NEXT VALEAF REC INTO COR  OR  ONTO
                  * THE SCRATCH FILE  EAF-EXCESS IF THE CORE BUFFS ARE FULL.
                  * EAF-RECS-BCNT IS  USED TO COUNT THE TOTAL NUMBER  OF
                  * RECORDS  SAVED FOR THIS PWS.
                  * VALEAF-REC-AVAILBL-INDIC IS USED  TO INDICATE THAT A RECORD NOT
                  * BELONGING  TO THIS PWS HAS BEEN FOUND.
                  * THIS  SECTION ALSO ACCUMULATES  SUMMARY  INFO  FOR SUBSEQUENT
                  * INASERTION INTO PWS-SUMMARY.
                  SAVE-VALEAF-RECS  SECTION.
                  SECT-ENTRY.
                       IF VEAF-ID  <  SAVE-ID MOVE VEAF-ID   TO RPT-PWS
                                           MOVE EAF-ID    TO RPT-REC
                                           MOVE EAF-TYPE  TO RPT-TYPE
                                           GENERATE  DETL
                                           PERFORM READ-NEXT-VALEAF
                                           GO TO  SECT-EXIT.
                       IF VEAF-ID  >  SAVE-ID MOVE 1      TO VALEAF-REC-AVAILBL-INDIC
                                           MOVE VAL-EAF TO SPEC-EAF-HOLD
                                           GO TO  SECT-EXIT.
                       MOVE I TO SUMM-EA-UPD.
                       ADD  1 TO EAF-RECS-BCNT.
                       ADD  1 TO SUMM-EA-CNT.
                       IF EAF-RECS-BCNT > EAF-RECS-BMAX
                                         PERFORM  WRITE-EAF-EXCESS
                       ELSE
                                         MOVE VALEAF TO VALEAF-BUP {EAF-RECS-BCNT).
                       PERFORM READ-NEXT-VALEAF.
                  SECT-EXIT. EXIT.
                  READ-NEXT-VALEAF SECTION.
                  SECT-ENTRY.
                      READ VALEAF AT END MOVE
                  SECT-EXIT. EXIT.
             1 TO EAF-EOFEOF.
1
Figure 7b.  Well-Formatted and Commented Code

                     8-15

-------
                                       IMPROVING READABILITY
          UNCLEAR:
            PTERM.
                    MOVE 0 TO ACCT-TIME-TOTAL ACCT-CAU-TOTAL ACCT-ALL-CNT.
                    MOVE ACCOUNT-KEY TO CURRENT-ACCT.
                    PERFORM PTERM UNTIL EOF-ACCOUNT OR ACCOUNT-KEY  NOT  = CURRENT-ACCT.
                    PERFORM CLEANUP.
                    STOP RUN.
                    MOVE 0 TO TERM-CNT.
                    MOVE TERM-KEYX TO CURRENT-TERM.
                    PERFORM PREC UNTIL EOF-ACCOUNT OR
                    OR TERM-KEYX NOT * CURRENT-TERM.
                                  ACCOUNT-KEY NOT - CURRENT-ACCT
          CLEARER:
            PTERM.
MOVE 0 TO ACCT-TIME-TOTAL
          ACCT-CAU-TOTAL
          ACCT-ALL-CNT.
MOVE ACCOUNT-KEY TO CURRENT-ACCT.
PERFORM PTERM UNTIL EOF-ACCOUNT
          OR ACCOUNT-KEY NOT = CURRENT-ACCT.
PERFORM CLEANUP,
STOP RUN.

MOVE 0 TO TERM-CNT.
MOVE TERM-KEYX TO CURRENT-TERM.

PERFORM PREC UNTIL EOF-ACCOUNT
          OR ACCOUNT-KEY NOT - CURRENT-ACCT
          OR TERM-KEYX   NOT - CURRENT-TERM.
t
                        Figure 8

                           8-16

-------
Programmers should be aware  of  the optimizations  that are done automatically
by the compiler.  This information is  in  the  programmer's reference manual
for the language.  Along with program  evaluation  tools, this knowledge will
enable programmers to write  more straightforward  source code.  Misapplied
optimization frequently leads to unclear  code.
8.5.2
Naming and Labeling Conventions
All names and labels in a program should be used to convey information such as
the function of the variable, routine, or label.  They may also convey order or
indicate logical relationships  to other variables, routines, or labels. Some
examples are as follows:
          Type of Name

            Flag

            Variable

            Label

            Entry point
                        Informative

                          PARITY

                          FILENO

                          INLOOP

                          EDIT
Uninformative

   OOPS

   XX

   S-3

   THERE
Mnemonics should be meaningful to other programmers.  In the examples provided
above, OOPS is probably meaningful to the original programmer, but it is
meaningless to others.  Use of 6-letter names in FORTRAN is encouraged;
other languages allow 12-, 32-, and even 132-character names.  Acronyms should
be defined somewhere in the code or external documentation.  Without a
definition, SRDPPR is almost as meaningless as XXXXXX.

If mnemonic statement labels are permitted, they should suggest the function
of adjacent code or the reason for referencing the statement.  In assembly
languages, all transfers of control should be directly to a label.  Relative
addressing should not be used because changing the number of instructions
alters program logic.
8.5.3
Expression and Computational Accuracy
Arithmetic, logical, and FORMAT statements should be properly punctuated and
written for human readability (Figures 9 and 10).  Expressions such as those in the
unclear examples do not conform to these guidelines for the following reasons.
First, different compilers evaluate logical expressions in different orders;
parentheses should be used to make the order of evaluation explicit.  Similarly,
                                     8-17

-------
                            IMPROVING READABILITY
UNCLEAR:
          BMOFF (1)=(JTIME-IBTAB(1))/(IBTAB(2).IBTAB(1))*(BMTAB(I49)-BMTAB(1D)
CLEARER:
          BMOFF (1) - (JTIME - IBTAB(l))  /  (IBTAB(2) - IBTAB(l))
        1           * (BMTABU+9)  -  BMTAB(l))
UNCLEAR:
          Y(l)=C(l,l)*Y(l>t-C(2,l)*Y(2)*Y{2HC(3,l)*Y(3)
CLEARER:
                     l) *Y(1)
        1      + C(2,l) *Y(2)  * Y(2)
        2      + C(3,l) *Y(3)
UNCLEAR:

CLEARER:
IF CNT1 - 3 OR CNT2 < D AND CNT4 >  CNT5  AND  FLG  > 0 GO  TO DONE
               IF (CNT2 < D)  AND  (CNT4 >CNT5)  AND  (FLG   > 0)
               OR (CNT1 = 3)
                              GO TO DONE
                                  Figure  9

                                     8-18

-------
                            IMPROVING READABILITY
UNCLEAR:
          IF I <= 1 THEN P = 0; ELSE IF I
          ELSE DO; S - SORT(I); J « 3;
          DO WHILE (J <= S); IF MOD (I,J)
          J - J + 2; END; P - 1; END;
                         2 THEN P - 1;

                         0 THEN DO; P = 0; GO TO DONE;
   DONE:
CLEARER:
          IF I  <=

          ELSE
1  THEN
  P = 0:

 IF I

 ELSE
                           2 THEN
                             P - 1;
                             DO; S - SORT(I);
                                 J - 3;
                                 DO WHILE (J  <= S);
                                    IF MOD (I,J)-0 THEN
                                                   DO; P = 0;
                                                       GO TO DONE;
                                                   END;
                                    J - J + 2:
                                 END;
                                 P - Ij
                                   Figure 10

                                    8-19

-------
            defaulting to precedence rules in arithmetic and  logical statements inevitably
            causes  errors.   These can be avoided simply by writing the expression in
            standard  mathematical notation.   Also,  because of binary hardware,  floating
            point arithmetic is  not  associative in  all  cases;  (A + B) + C does  not always
            equal A + (B +  C).   When operations on  either very large or very small numbers
            are  involved, programmers must specify  an order of evaluation to avoid
            numerical  errors.  Proper use of  parentheses increases computational  accuracy.
            There is  also a much greater chance of  typographical and logical errors when
            arithmetic,  logical,  or  FORMAT expressions  are packed together.   Without
            spaces  between  operators and operands,  floating point logical expressions  can
            be very difficult  to  read.   It is much  easier to  verify the correctness of
            the  properly formatted expressions,  as  shown in Figures 9 and 10.

            Problems  arise  when  quantities of greatly differing  orders  of magnitude are
            combined.   Some of these problems result because many decimal fractions do
            not  have  exact  binary representations.  Also,  differences  in machine  accuracy
            (due to differing word length and internal  floating  point  representations)
            make many  high-level  language programs  machine dependent.   It  should  be  noted
            that there are  two representations  for  zero  on one's  complement  computers
            (such as  the UNIVAC  1100 series).   Parentheses should be used  to  specify an
            order of  evaluation,  giving  the best accuracy.  Users  of certain  types  of
            mainframes have  experienced  problems with mixed-mode  arithmetic  involving
            double-precision variables.   These  problems  can be eliminated  by using  explicitly
            declared double-precision variables  instead  of relying  on the  compiler  to
            propagate  double-precision results  through mixed-mode  expressions.
I
8-20

-------
                  8.5.4     Acce p tab 1 e Program Structures^

                  The formallzation of programming disciplines has produced three basic program
                  control structures by which any program function can be performed.  It is
                  recommended that all programs follow these constructs so as to promote uniform
                  coding practices and avoid the difficulties so frequently associated with
                  unstructured code.  The three basic constructs - sequence, repetition, and
                  case - are illustrated in Figure 11 and are represented by COBOL, PL/1, and
                  FORTRAN examples in Figures 12, 13, and 14.
 c
«
8-21

-------
SEQUENCE:
REPETITION:
CASE:
                Figure 11.    Program Structure Types




                                8-22

-------
COBOL
          PERFORM   PROCESS-A.
          PERFORM   PROCESS-B.
          PERFORM   PROCESS-C.
FORTRAN
     aaOl statement al
     aa99 CONTINUE
     bbOl statement bl
     bb99 CONTINUE
     ccOl statement cl
     cc99 CONTINUE
                               The prefixes aa, bb, and cc are used to
                               uniquely identify each block.
The suffix 01 indicates the beginning
of a sequence block.

The suffix 99 indicates the end of a block.
PL/1
       CALL   PROCESS-A;
       CALL   PROCESS-B;
       CALL   PROCESS-C;
                      Figure 12a.  Sequence Structures

                                    8-23

-------
COBOL
          A-BODY-SEQ.
               statement  1
                              PL/1
                                  A BODY SEQ: DO; statement 1;
     statement n
A-BODY-END. EXIT.

B-BODY-SEQ.
     statement 1
                                                            statement n;
                                                        END A BODY SEQ;
                                            B BODY SEQ: DO; statement 1;
               statement n
          B-BODY-END. EXIT.

          C-BODY-SEQ.
               statement I
               statement n
          C-BODY-END. EXIT.
                                                  statement n;
                                              END B BODY SEQ;
                                  C_BODY_SEQ:  DO;  statement 1;
                                                  statement n;
                                              END C BODY SEQ;
These alternate coding sequence schemes are provided for those cases when it
may be considered undesirable to branch to a separate part of the program.
                       Figure 12b.   Sequence  Structures

                                     8-24

-------
 COBOL
       PERFORM PROCESS-A UNTIL NOT e.
       A-BODY-ITR.
           IF NOT e GO TO A-BODY-END.
           statement 1.
    PERFORM PROCESS-A.
    PERFORli PROCESS-A UNTIL e.

 A-BODY-ITR.
    statement  1.
           statement  n.
           GO  TO A-BODY-ITR.
      A-BODY-END.  EXIT.

PL/1

      DO WHILE  (e);  •
         CALL PROCESS_A;
      END;

      P_BODY_ITR:  IF (e)  THEN
                           DO;  statement  1;
                               statement  n;
                           END;
                   GO TO P__BODY__ITR;
      P_BODY_END:

FORTRAN

  aa02    IF(.NOT. e)GO TO aa99
          statement 1
    statement  n.
    IF NOT  e GO TO A-BODY-ITR,
A-BODY-END. EXIT.
 CALL PROCESS_A;
 DO UNTIL  (e);
   CALL PROCESS_A;
 END;

 P_BODY_ITR: DO; statement 1;
                statement n;
            END;
            IF (-ie) THEN
               GO TO P_BODY_ITR|
P BODY END:
aa02    statement 1
          statement n
          GO TO aa02
  aa99    CONTINUE
        statement n
        IF(.NOT. e) GO TO aa02
aa99    CONTINUE
                      Figure 13.  Repetition Structures

                                    8-25

-------
           COBOL
            or
IF (case-1-condition) PERFORM-CASE-1.
IF (case-2-condition) FERFORM-CASE-2.
IF (case-3-condition) PERFORM-CASE-3.

A-BODY-SEL.
    IF (NOT case-l-condition)GO TO A-BODY-ALT-01.
            (body of case 1)
    GO TO A-BODY-END.
A-BODY-ALT-01.
    IF (NOT case~2-condition)GO TO A-BODY-ALT-02.
            (body of case 2)
    GO TO A-BODY-END.
A-BODY-ALT-02.
    IF (NOT case-3-condition)GO TO A-BODY-END.
            (body of case 3)
    GO TO A-BODY-END.          (Note: inclusion of this GO TO facilit-
A-BODY-END. EXIT                ates the addition of future alternatives.)
           PL/1
I
            or
                 IF (case-condition-1) THEN CALL PROCESS_CASE_1;
                 IF (case-condition-2) THEN CALL PROCESS_CASE_2;
                 IF (case-condition-3) THEN CALL PROCESS_CASE_3;
           A BODY END:
                               IF(case-l-condition)  THEN
                                                     DO; statement I;
                                                         (body of case 1)
                                                         statement n;
                                                     END;
                                                     THEN
                                                     DO; statement 1;
                                                         (body of case 2)
                                                         statement n;
                                                     END;
                                                     THEN
                                                     DO; statement 1;
                                                         (body of case 3)
                                                         statement n;
                                                     END;
                   Figur* 14a.  CASE Structures

                               8-26
A BODY SEL:
    ELSE IF (case-2-condition)
    ELSE IF (case-3-condition)

-------
I
                FORTRAN (1977 ANSI Standard)

                      aa03     IF           (case-1-condition) THEN
                                                  •
                                                  »
                                                  •
                               ELSE IF      (case-2-condttion) THEN
                                                  •
                                                  •
                                                  •
                               ELSE IF      (case-3-condition) THEN
                               END IF
                      aa99     CONTINUE
                FORTRAN (alternative)
                      aa03     IF (.NOT.  case-1-condition) GO TO aa04
                               GO TO aa99
                      aaOA     IF (.NOT.  case-2-condition)  GO TO  aa05
                               GO TO aa99
                      aa05     IF (.NOT.  case-3-condition)  GO  TO  aa99
                               GO  TO aa99
                      aa99     CONTINUE
Figure 14b.  CASE Structures
            8-27

-------

           8.5.5
Language Usage and Restrictions
           There  are a number  of features and programming liberties provided or allowed
           by  high-level and assembly languages which have caused a disproportionate
           number of errors  and which tend to cause new bugs when compiler or operating
           system versions change.   In the interest of more dependable systems, which
           are easier to debug and  maintain,  the use of many of the practices or features
           discussed herein  is discouraged.

           It  is  considered  poor programming  practice to rely on defaults  provided  by
           the language.   Although  these  seem to speed up initial development (by saving
           the few seconds it  takes to write  something out fully),  they may not be
           obvious to the maintenance programmer,  and default parameters change.  Debugging
           and maintenance are simplified if  all processing procedures and parameters
           are completely written out.  The general rule is to be explicit.   This includes
           parenthesizing arithmetic  and  logical expressions  to force  the  desired order
           of  evaluation.  All subscripts should be written out even though some languages
           allow  them to  be  omitted.   The arguments passed between  routines must agree
           in  number  (none should be  omitted),  order,  and type.
          8.5.5.1   FORTRAN

          The following considerations  should  be  taken when coding in FORTRAN.
          these points apply as well  to PL/1.
                                                            Most  of
                         Subscripts - All subscripts must be explicitly written oat;
                         none should be omitted.  Exceptions include situations in which
                         an entire array is referenced in an output list, data state-
                         ment, or calling sequence.

                         Internal subroutines - With some compilers the definitions of
                         local and global entities are complicated in internal subroutines.
                         Use of this feature may degrade reliability; therefore, it
                         should be used with caution.

                         Multiple subroutine entry points and nonstandard returns - Use
                         of this feature confuses program logic because control flow
                         between subroutines is obscured, which results in systems that
                         are several times more difficult to debug.  A unit of code
                         should have only one entry point and one exit point.  Non-
                         standard entry points and returns should not be used.
I
                          8-28

-------
                           •    Branching statement - The FORTRAN logical IF statement, as in

                                          IF (IFILES .LT. LIMIT) CALL MASTHD

                                is superior to the arithmetic IF or any of the nonstandard
                                variations currently on the market because it clearly states
                                decision criteria and has simple, predictable branching
                                effects.  The arithmetic IF, as in

                                          IF (NTERMS)  10,6,23

                                is not self-explanatory, and it forces at least two GO TOs
                                and two more statement labels on the programmer.   It is
                                unnecessary and should not be used.


                                The assigned GO TO, as in

                                          ASSIGN 6 TO SWITCH
                                          GO TO SWITCH
                                confuses program logic,  complicates debugging,  and  can easily
                                be abused without generating compiler  diagnostics*

                                The computed GO TO,  as in

                                          GO TO (10,20,30,40),  INDEX

                                may be used  to  implement decision tables  and  case structures.
                                When the index  is negative,  zero,  or out  of limits,  the results
                                may be unpredictable.   For  this reason, computed GO  TOs should
                                be preceded  by  a test  for a  valid index.

                                Every upward GO TO in  a  program creates a potential  loop.
                                Therefore,  they should be used  solely  for the purpose  of
                                implementing loops and not  for  picking up a few lines  of code
                                or for patching faulty logic.

                                PAUSE and STOP  - The FORTRAN PAUSE statement  should  not be used
                                because it requires  operator intervention.  STOP statements
                                must have associated messages that Identify the program elements
                                to which they belong.
I
8-29

-------
                          LOOPS - All program loops should be explicit; that is, the
                          loop body should be separated from surrounding code and should be
                          preceded by a prominent comment.  All FORTRAN DO loops should end
                          with a CONTINUE statement, one for each loop.  All programmer-
                          implemented loops (DO WHILE, DO UNTIL) should begin with a
                          CONTINUE statement.  The contents of a loop are indented one
                          level (four or five spaces) for each level of nesting (see
                          Figures 4 and 7).

                          IMPLICIT - The variables affected by this feature must be
                          consistent for every routine in a program.

                          PARAMETER - There are other means of parameterization In
                          FORTRAN; again, unless used consistently (the user should be
                          wary of COMMON), it can lead to confusion.  Before using this
                          feature, the FORTRAN manual should be read carefully,  giving
                          attention to the numerous important restrictions.  It  may be
                          desirable to use another method, even if it takes more work
                          initially*

                          MIXED-MODE EXPRESSION - these should be made explicit.  Mode
                          conversions should be performed by calls to the appropriate
                          conversion routine so as to avoid misunderstandings with implied
                          conversion.

                          EQUIVALENCE - This is a standard feature which can be  easily            /"
                          abused*  It must not be used to extend the length of arrays.
                          Use of EQUIVALENCES can also complicate debugging because
                          subscripts must be mapped into their corresponding locations.
                          The FORTRAN manual should be read carefully before using
                          this feature.
           8.5.5.2   COBOL

           8.5.5.2.1    General  COBOL Guidelines
                          Use ANSI Standard COBOL as much as possible - this will greatly
                          facilitate transporting the program between computer  facilities
                          as well as improve understanding on the part of  programmers
                          from other Installations.

                          Division headers should appear at the  top of the page and
                          should be separated from the body of the division by  one or
                          more blank lines.
I
8-30

-------
f
I
                                There  should  be  at  least  one  blank line  between  a  section
                                header and  the body of a  section.

                                Use  of columns 1-6  and 73-80  should be consistent  throughout
                                all  programs  and subroutines  of a system.
8.5.5.2.2   IDENTIFICATION DIVISION Guidelines

          •    This division should include the PROGRAM-ID,  AUTHOR,  INSTALL-
               ATION, and DATE-COMPILED paragraphs.

          •    This DIVISION should contain the prolog described in
               Section 4.1 with appropriate modifications pertinent  to COBOL.

          •    Once a program has been placed into production, every modifi-
               cation should include comments that contain the following:

               a.   an index of the current modification

               b.   a description of and the rationale for the changes made

               c.   the date and person making the change.

          •    The AUTHOR paragraph should list the names of all persons who
               have made changes to the program.


8.5.5.2.3   ENVIRONMENT DIVISION Guidelines

          •    Internal file names, the ASSIGN TO, and external file names
               within SELECT statements should be aligned in columns.

          •    Each clause subordinate to a SELECT/ASSIGN TO statement should
               appear on a separate line underneath the ASSIGN TO, as follows:
                              t
                    SELECT MASTER-IN   ASSIGN TO MASS-STORAGE OLD-MASTER.

                    SELECT MASTER-OUT  ASSIGN TO MASS-STORAGE NEW-MASTER.

                    SELECT SUMM-RPT    ASSIGN TO PRINTER      SUMMARY.

                    SELECT XREFFILE    ASSIGN TO MASS-STORAGE XREFFILE

                                       ORGANIZATION IS INDEXED

                                       ACCESS IS RANDOM

                                       ACTUAL KEY IS XREF-ID.
                                                       8-31

-------
           8.5.5.2.4      DATA DIVISION Guidelines

                     •    Clauses within an  FD should appear on separate lines under the
                          FD file name and FDs should appear in the same order as the
                          corresponding SELECT statements.
                               FD   MASTER-IN

                                    LABEL RECORDS ARE STANDARD

                                    RECORDING MODE IS F

                                    BLOCK CONTAINS 153 RECORDS

                                    RECORD CONTAINS 473 CHARACTERS.
                          Each 01 level item should be preceded by one or more blank
                          lines.

                          Item names, PICTURE, USAGE, and VALUE clauses for items at the
                          same level should all be aligned in columns.

                          If an item has both USAGE and VALUE clauses, align the VALUE
                          clause beneath the USAGE.  If a VALUE literal will not fit on
                          one line, it should be placed on a separate line beneath
                          the item name.

                          Each level in a data structure definition should be Indented
                          four spaces from the previous level.  This greatly facilitates
                          the understanding of the structure.

                          String lengths within PICTURE clauses should always be specified
                          in parentheses - even if the length Is a single character.  This
                          reduces the probability of error and eases the checking of
                          group lengths.

                          The use of 88 level Items is highly encouraged.  This simplifies
                          the understanding of Procedure Division code.

                          The use of 77 level items should be avoided.

                          Constants should appear at the beginning of WORKING-STORAGE
                          along with their associated VALUEs.  Variables should not be
                          initialized with VALUE clauses - they should be initialized
                          by the program.
I
                                                8-32

-------
                           01
                           01
                           01
                           01
PROG-VERSION

RECS-IN

REGS-OUT
                 PIC X(4)

                 PIC 9(10)

                 PIC 9(10)
VALUE 'V3.2',

USAGE COMP.

USAGE COMP.
HOLD-REC.
02  HOLD-REC-ID       PIC 9(4).
02  HOLD-REC-TYPE     PIC X(l).
02  HOLD-REC-DATE.
    03   HOLD-REC-YY      PIC 9(2).
    03   HOLD-REC-MMDD    PIC 9(4).
02  HOLD-REC-QUANT    PIC 9(5)V9(1).
                 8.5.5.2.5      PROCEDURE DIVISION Guidelines

                           •    Multiple objects of a single statement should be lined up  in
                                columns with one object per line.

                                     OPEN INPUT   MASTER-IN
                                                  FARM-FILE
                                                  XREF-ADDR-FILE.
                                     MOVE 0 TO REC-CNT
                                               LINES-OUT
                                               TAB-PTR.

                           •    Operators and operands in continued statements or groups of
                                similar statements should be aligned in columns.
                                     MOVE OLD-ID
                                     MOVE ID-TOTAL
                                     MOVE ZEROES
                         TO PRT-LINE-ID.
                         TO PRT-LINE-TOTAL.
                         TO ID-TOTAL.
                                     COMPUTE YEARLY-TOTAL - QTR1-TOTAL + QTR2-TOTAL
                                                          + QTR3-TOTAL + QTR4-TOTAL.

                                IF statements should not be nested deeper than three levels.
                                Deeper nesting is usually very difficult to understand.  If
                                deeper nesting is required by the problem at hand, then the
                                lower level nesting should be performed elsewhere.

                                Each ELSE should be aligned with Its corresponding IF.

                                Each condition of compound IPs should appear on a separate
                                line.  Parentheses should be used to simplify understanding
                                of the relationships between the conditions.

                                Subjects of IFs and ELSEs should be aligned in columns after
                                the object conditions.
I
                      8-33

-------
                                   IF
                                      AND
(BMP-TENURE
CBMP-AGE
                                   ELSE
40)
60)
                   ADD 1 TO TYPE1-CNT
                   PERFORM PROCESS-TYPEA

                   PERFORM CHECK-TYPES-B-F.
                                   STOP RUN should appear only in the driver SECTION.

                                   PERFORM THRU should not be used.

                                   The VARYING FROM,  BY and UNTIL clauses on a PERFORM should
                                   appear on separate lines aligned  under the PERFORMed section
                                   name.   The VARYING index should not,  of course,  be altered
                                   by the PERFORMed section.
                                        PERFORM LOAD-REC-BUFF
                                                VARYING BUFF-PTR FROM 1  BY 1
                                                  UNTIL BUFF-PTR >  BUFF-SIZE
                                                     OR REC-ID-CHANGE
                                                     OR END-OF-MASTER.
                                   All  I/O operations  should  be  isolated  into  separate  SECTIONS.
                                   This makes  the  details  of  such  operations more  transparent  to
                                   the  program and simplifies the  reading and  modification of
                                   the  program.

                                   All  arithmetic  computations involving  more  than one  operation
                                   should  be performed with the  COMPUTE verb.   The only exception
                                   is that the DIVIDE  verb may be  used if a remainder is required.
                                   In this case, DIVIDE BY should  be used and  not  DIVIDE INTO.

                                   Parentheses should  be used to simplify the  understanding of
                                   complex arithmetic  statements or wherever confusion  may arise
                                   as to the order of  evaluation of a statement.

                                       COMPUTE ROOT «= (DISC  - B)  / (A +  A).

                                       COMPUTE ADJUSTED-INT  - BASE-INT * (NUM-PDS - 1)
                                                             + BASE-VAL / (NUM-PDS +1).
I
            8-34

-------
                         8.5.5.3   PL/1
                         8.5.5.3.1       General Guidelines

                                   •    Each PROCEDURE should appear at the top of a page.   If a
                                        particular implementation of PL/1 does not allow this, then
                                        sufficient blank lines should be used to clearly separate the
                                        PROCEDURE from other PROCEDURES.

                                   •    Each PROCEDURE should be followed by a prolog as described in
                                        Section 7.4.1, followed by the procedure's DECLARES,  followed
                                        the body of the procedure.

                                   •    Nested  statements should be indented several spaces  for each
                                        level of nesting.   The degree of indenting should be  chosen so
                                        as  to align the indented statements in a reasonable  manner.

                                   •    Avoid the use of columns 1 and 73-80 for program text.


                         8.5.5.3.2       DECLARE Guidelines

                                   •    DECLARE procedure  arguments before local variables and in the
                                        order they appear  in the PROCEDURE statement.

                                   •    Constants should appear before variables.   Constants  should
                                        be  initialized in  their DECLARE statements whereas variables
                                        should  be initialized  in the body of the procedure.

                                   •    Unrelated items should be placed in separate DECLARE  statements|

                                   •    Related items appearing in the same DECLARE should be  placed
                                        on  separate lines  with item names and attributes  aligned  in
                                        columns.

                                   •    Structured definitions should appear with  one  item per line
                                        and each level of  the  structure indented an appropriate number
                                        of  spaces.
DECLARE PI          FLOAT
        TAB_SIZE    FIXED
DECLARE 1 TIME_CARD,
          2 NAME        CHARACTER(30),
          2 SSN         FIXED(9)
          2 HOURS_CHARGED,
            3 STRAIGHT   FIXED(3),
            3 OVERTIME   FIXED(3),
          2 BASE PAY    FIXED(2,2);
                                                                           INITIAL(3.14159),
                                                                           INITIAL(139);
I
                 8-35

-------
I
                           Avoid  the use of DECLARES with factored  attributes:
                           DECLARE (I,  J,  K) FIXED;
            8.5.5.3.3       PROCEDURE Body Guidelines
                           Each procedure should be  entered  only  at  its  top  and  exited
                           at  its  END.   Do not  use ENTRYs.

                           Each END  should appear on a  line  by  itself  and  should be
                           aligned under the  beginning  of  the statement  with which
                           it  is associated .

                           Avoid the use of BEGIN blocks.  Use  separate  procedures
                           instead.   Since a  BEGIN block is  logically  a  discrete
                           procedure, the text  of the BEGIN  block can  only impede
                           understanding the  program flow.

                           Avoid the use of subscripted labels.   They  may  appear to  be
                           a convenient  feature,  but their use  is often  unfathomable by
                           the  maintenance programmer.

                           Do not  use local variables whose  names duplicate  global
                           variables.

                           Do not  nest IF statements deeper  than  three levels.   If deeper
                           nesting is required  by the problem at  hand, separate  IPs
                           or procedures should be used instead.

                           Each IF THEN  ELSE  should  have the THEN and  ELSE aligned under
                           the  IF, as shown below.

                           IF condl
                           THEN DO;
                                  statement 11;
                                  statementln;
                               END;
                          ELSE DO;
                                  statement  21;
                                  statement  2n;
                               END;
8-36

-------
                                                            APPENDIX A




                                                            GLOSSARY
I

-------
                                           APPENDIX A - GLOSSARY
               Accuracy - Precision or exactness, or freedom from error, of the results of
                          a computation or a program.

               Component, Hardware - Any of the main constituent parts of the physical equip-
                          ment included in the computer system.

               Component, Software - A discrete set of program instructions which may be
                          handled as a unit for compilation and loading.

               Configuration - A particular combination of hardware (CPU, disks, tapes,
                          etc.) and software (operating system, utilities, etc.).   Typically
                          used in "minimal configuration", i.e., the minimal hardware and
                          software requirements for a particular application.

               Control Language - A language used to specify job level processing requests
                          to an operating system.  This language will vary from computer
                          to computer (e.g., ECL on UNIVAC 1100, JCL on IBM 360/370).

               Data Base - A collection of data, usually integrated and organized for ease
                          of retrieval and maintenance.

               Data Base Management System - A collection of software that provides a wide
                          variety of data manipulation capabilities that allow a user to
                          organize data in a meaningful and useful nanner.

               Data File - A collection of related data records, usually organized to meet
                          a specific purpose and often sequenced in accordance with a key
                          contained in each record.

               Data Group - A collection of related data items within a data record.

               Data Item - A specific unit of information to which meaning can be  assigned,
                          represented in signs or symbols which can be interpreted by a
                          person or by a machine.

               Data Record - A collection of related data items treated as  a unit,  specifi-
                          cally for input-output purposes.

               Design Methodology - An orderly, logical procedure or approach  to the  design
                          of a computer system.

               Developmental Impact - The effect of a system change, enhancement,  or  redesign
                          on the implementation schedule of a system or program.

               Diagnostic - A message from a program (user or system)  indicating that the
                          program has detected a possible error condition.
I
A-l

-------
I
                                APPENDIX A - GLOSSARY (continued)


          Documentation - A collection of written or printed items that aid in the
                     understanding of a system or program.

          Enhancement - An extension and improvement in the features and capabilities
                     of an existing computer program or system.

          EPA ADP Manual - The document issued by the Environmental Protection Agency
                     that details data and information processing policies and procedures.

          FIPS (Federal Information Processing Standards) -  Publications of the
                     National Bureau of Standards relating to automated data systems.

          Hardware - The physical components (mechanical, magnetic, electronic, or
                     electrical) of a computer system.

          Host Computer - The primary computer used by a particular system.

          Interactive - A mode of communication between a computer system and a person
                     via a terminal, In which a query/response "dialogue" is conducted.

          Interface - Linkage or other arrangement or convention established for
                     communication between hardware and/or software components, such  as
                     program-program,  computer system-operator,  and computer syster.-
                     terminal user.

          Job - A specific anount of work to be performed by a computer,  involving one
                     or many  processes,  programs,  etc.

          Key - One or more characters used to uniquely identify a data item or a
                     data record within a data file.

          Log-On - The process of establishing a communications  link with a  computer
                     and identifying oneself for accounting purposes.

          Macro - A block of  source code text that is used by certain system utilities
                     as a template for generating source code.

          Maintenance - Performance of support functions to modify,  update,  and correct
                     computer programs;  also to update,  correct, and purge data files;
                     also to  maintain hardware on a scheduled or corrective  basis.

          Medium (Media) - The physical  manifestation of stored  data or programs such
                     as punch cards,  magnetic tape,  disk,  paper  tape,  cassettes, etc.

          Mnemonic - A device or technique  intended to  help the  memory.

          Modularization - The organization of a program into sets of instructions which
                     may be treated as discrete units.
A-2

-------
                                      APPENDIXA - GLOSSARY (continued)


                Module - A discrete set of program instructions which may be treated as a unit.

                On-Line - The direct communication of a particular hardware component with
                           another, especially with one under control of the other; also
                           access to a computer system by a person via a terminal.

                Operating Environment - The conditions under which a program or system operates.
                           This includes the physical state of hardware as well as conditions
                           such as job and user mix.

                Operating System - The software components which provide control of all
                           elements of computer system functions, including executive, call,
                           and loading routines; hardware assignment; multiprocessing; and
                           input-output operations.

                Operational Characteristic - A distinguishing feature or quality of the
                           method by which a data processing function is performed.

                Operational Controls - Procedures,  usually manual, which effect the continued
                           processing of a system,  such as approval procedures, confirmation
                           of successful completion of one program before initiation of the
                           next, and file cycle validation.

^P             Operational Function - A defined action by the computer syster. which controls
 V                         data recording, transmission,  interpretation, or other processing.

                Operational Impact - The effect of  a  system change, enhancement, or redesign
                           on the way in which a program or system is used.

                Operational Procedure - The steps and actions  performed in accordance with
                           user policies in the functioning of a computer system.

                Organizational Impact - The effect  of a system change,  enhancement,  or re-
                           design on the personnel  structure under which a system or program
                           functions.

                Output.Display - A visual representation of information,  such as  on a CRT
                           screen, usually read and acted upon before a subsequent action
                           is to take  place.

                Output,  Graphic - Data written in representational or pictorial form,  such
                           as mathematical curves,  histograms, contour plots,  or maps.

                Portability - The ease with which data or programs may be transferred from
                           one computer system to another.
I
A-3

-------
                                         APPENDIX A - GLOSSARY  (continued)
I
                   Program - A sequence of data processing instructions or statements in a
                              form acceptable to, and intended for execution on, a computer.

                   Query Language - A language used to specify interactive processing requests
                              to a Data Base Management System.

                   Reference File - A data file used by a program for reference purposes such
                              as validating data items or retrieving detailed information about
                              a data item.

                   Report Generator - A program whose primary purpose is to produce a report
                              or reports based upon provided input parameters.   Most computer
                              sites have a report generator utility that can produce reports
                              from many types of input files.

                   Response Time - Elapsed time between the sending of a signal or message and
                              the receipt of an answering signal or message.   This is typically
                              a measure of how quickly an operating system can react to a
                              processing request from an on-line terminal.

                   Responsiveness - The ability of the computer system to meet  the needs of the
                              user on a timely basis,  especially in interactive mode.

                   Software - Computer data,  information,  programs,  compilers,  routines, etc.,
                              that work in conjunction with the hardware to accomplish data
                              processing functions.

                   Software,  Application - Computer software used for specific  user needs,  such
                              as payroll, accounting,  scientific calculations,  or inventory
                              control.

                   Software,  System or Support - Computer  software used to provide common data
                              processing functions to  many users.

                   Source Code - The symbolic text of  a program.   This is the form in which
                              programs  are written and read by programmers.

                   Subroutine - A set of coded instructions that performs a certain function
                              within a  program or that exists in a library and  may be referenced
                              by other  programs for incorporation therein.

                   Subsystem  - A related set  of programs  that function together to perform  a
                              portion of a data processing application;  linked  with other
                              subsystems to form a system.

                   System - An integrated set of programs  or subsystems that  function together
                              to perform a data processing application.
A-4

-------
                                       APPENDIX A - GLOSSARY (continued)
                 System Flow Diagram - A pictorial representation of  the  overall  flow of  data
                            and control through the system;  its  purpose is  to  graphically
                            represent the relationships  between  programs, subsystems,  files,
                            and major I/O functions.

                 Testing Tools  - Utility programs  or  semi-automated procedures  intended to
                            aid in the testing  or  debugging  of a system or  program.   These
                            include items such  as  test, data  generators, program execution
                            monitors, and dump  analyzers.

                 Throughput  - The amount of  work produced  by a computer system, normally
                            measured in jobs per day  or  per  hour.

                 Top-Dovn -  A method of design  in  which  the  general design  is presented first,
                            followed by successive refinements of  detail, until a final precise
                            design is reached.  This  is  also termed "step-wise  refinement".

                 User  - A person or organization who  employs or  applies,  for his own  needs,
                            the hardware or  software  components  of a  computer system.

                 Utilities - Programs in the systec library  that are  frequently used  by most
                            of  the system's  users.  These  include  items such as sort, copy,
                            and dump utility prograns.
I
A-5

-------
                                             APPENDIX 3
                                CHARTING CONVENTIONS FOR SYSTEM DE\ELOPMENT
                BASIC SYMBOLS.  A  basic  symbol  is  established for each
                      .on and can be  always  used to represent  that function.
                      ilised symbols  are  established which  may be  used in
                      of a basic symbol  to  give additional information.
   1
1.  IZCPUT/OUTPUT
           2.   PROCESS
          3 .  FLOWLIirz

          4.  ANNOTATION,
          5.
                                 This symbol represents the input/
                                 output (I/O)  function, i.e.,  the
                                 making available of information
                                 for  processing (input) or
                                 recording processed information
                                 (output).


                                 This symbol represents the processing
                                 function i.e., the process of
                                 executing a defined operation or
                                 group of operations resulting in a
                                 change in value, form, or location
                                 of information or in the deter;ninati<
                                 of which of several flow directions
                                are to be taken.

                                This  symbol  represents the flowline
                                function,  i.e., the indication of
                                the sequence of available infor-
                                mation  and executable operations.


                                This  symbol  represents  the  annotation!
                                function, i.e., the  addition of
                                descriptive  comments or explanatory
                                notes as clarification,
                                          This symbol represents  an  operation
                                          using a key driven device  -  such  as
                                          punching, verifying, typing.
I

I/O syir.bol jnay  be  used.
                                                         s i
                                                         the  basic
                                  JS-1

-------
       SYMBOL	

       1.  PUNCHED CARD
  USE

       2.  MAGNETIC TAPES,
       3.  PUNCHED TAPS.
       4,   DOCUMENT.
          KAXUAL  INPUT.
      6-  DISPLAY.
      7.  COMKUKICATION LINK
I
      6.  KRSKZTIC DRUM.
 For  an I/O function in which the
 medium is punched cards, including
 mark sense cards, partial cards, stub
 cards, etc.
 For an I/O function in which the
 medium is magnetic tape.
 For an I/O function in which the
 medium is punched tape.
 For an I/O function in which the
 mediua is  a document.
 Tor an I/O function in which  the
 information is entered manually
 at the time of processing, by means
 of online keyboards, switch settings,
 push buttons, card readers,etc.

 For an I/O function in which  the
 information is displayed for  human
 use at the time of processing, by
 means of online indicators, video
 devices, console printers, plotters ,
 etc.

 For an I/O function in which  infor-
 mation is transmitted automatically
 from one location to another.
For an I/O function in which infor-
mation for processing (input) or the
recording of processed information
(output) is stored online on magr.etic
drum.
 B-2

-------
             SYK3OL
              9.  MAGNETIC DISK
             10.   TRANSMITTAL TAPE
             11.   ONLINE STORAGE.
                    r
            12.  OFFLINE STORAGE
                         V
              ,   CORE.
                             USE
                           For  an I/O function in which infoj
                           mation for processing (input) or tl
                           recording of processed information]
                           (output) is stored online on magnef
                           disc.
                           Proof or Adding Machine tape, or
                           other batch control information.
                           For an I/O function utilizing
                           auxiliary  mass storage of infor-
                           mation that can be accessed online,
                           e.g. magnetic   drums,  magnetic discs,
                           magnetic tape,  automatic magnetic
                           card systems,  or automatic chip  or
                           strip systems.

                           For any offline storage of infor-
                           mation,  regardless of the medium on
                           which the information is recorded.
                          Represents an I/O function in which
                          the medium is magnetic core.
            C.   SPECIALIZED PROCESS SYMBOLS.  Specialized process symbols
may represent  the processing function, and in addition,
identify the specific type of operation to be performed
the information.  If no specialized symbol exists, the
basic process  symbol may be used.
                                                                        on
I
             SYMBOL
                         USE
             1.   DECISION.
                         Represents a decision or switching
                         type operation that determines which
                         of a number of alternate paths it is
                         to be followed.
                              B-3

-------
            SYMBOLS
I
         2.  PREDEFINED PROCESS.
        3.  AUXILIARY OPERATION,
        4.  MANUAL OPERATION.
       5.
                  O
        6.  TERMINAL,
        7.   PREPARATION.
        8.   COLLATE,
        9.   MERGE,
  USE
 Represents a named process consistin
 of one or more operations or prograir
 steps that are specified elsewhere.
 e.g., subroutine  or logical unit.
 Represents  an offline  operation
 performed on equipment not under
 direct  control of the  central pro-
 cessing unit.
Represents any offline process
geared to the speed of a human
being.
Represents a junction in a line
of flow.
Represents a terminal point in a
system or communication network
at which data can enter or leave.
e.g., start, stop, halt, delay or
interrupt.

Represents modification of an in-
struction or group of instructions
which change the program itself,
for example, set a switch, modify or
index register,  and initialize a
routine.

Represents merging with extracting,
that is, the formation of two or
more other sets.
Represents the combining of two
or more sets of items into one
set.

-------
          SYMBOLS
 USS
        1C.  EXTRACT,
        11.   SORT.
       12.  PARALLEL  MODS.
 Represents the removal of one or
 more specific sets of items  from
 a single set of items.
Represents the arranging of a set
of items into a particular sequence,
Represents the beginning or end
of two or more simultaneous
operations.
I
                                        b-5

-------
                                                     APPENDIX C




                                                    BIBLIOGRAPHY
  1
I

-------
                                               APPENDIX C
                                              BIBLIOGRAPHY
            1.        Auerbach Publishers,  Inc.,  "Objectives  of  Structured  Programming",
                      Auerbach_Programming  Management,  Section 14-02-01, 1974

            2.        N. Wirth,  "Program Development by Stepwise Refinement", Communica-
                      tions of the ACM, vol.  14,  no. 4, April 1971

            3.        J. Aron, The Program  Development  Process (Parts  I and II).   Reading,
                      Massachusetts:  Addison-Wesley, 1974

            4.        C. McGowan and J. R.  Kelly, Top-Down  Structured  Programming
                      Techniques.  Reading, Massachusetts:  Addison-Wesley, 1975

            5.        S. H. Caine and E. K. Gordon, "PDL -  A  Tool for  Software Design",
                      Proceedings of 1975 AfIPS National Computer Conference

            6.        W. P. Stevens, G* J.  Myers, and L.  L. Constantine,  "Structured
                      Design", IBM Systems  Journal, no.  2, 1974

 «          7.        D. L. Parnas, "On the Criteria To Be  Used  in Decomposing Systems
                      into Modules", Communications of  the  ACM,  vol. 15, no. 12,
                      December 1972

            8.        D. L. Parnas and D. P.  Siewiorek,  "Use  of  the Concept  of Transparency
                      in the Design of Hierarchically Structured Systems",  Commun icationg
                      of the ACM, vol. 18,  no. 7, July 1975

            9.        E. Yourdon, Techniques  of Program Structure and  Design.  Englewood
                      Cliffs, New Jersey:   Prentice Hall, 1975

           10.        B. W. Kernighan and P.  J. Plauger,  The  Elements  of Programming
                      Style.  New York, New York:  McGraw-Hill, 1974

           11.        G. Lowrimore, Applications  Systems Development;  A Better Way.
                      EPA DATA TALK, May 1978
   rf

           12.        M. H. Weik, Standard  Dictionary of Computers and Information
                      Processing. Rochelle  Park,  New Jersey:  Hayden Book Company,  Inc.,
                      1977

           13.        M. A. Jackson, Principles of Program  Design.  New York, New  York:
                      Academic Press, 1975
I
C-l

-------