February 1985 Circular 605
Guidelines for Software Development,
Documentation and Review
COMPUTER SERIES I
\I8;:V~K. M. teA. B. Bottcher, T. R. Hintz, W. E. Kunkle
Florida Cooperative Extension Service / Institute of Food ad Aglricultural Sciences / University of Floria~ / John T. Woeste, Dean
GUIDELINES FOR SOFTWARE DEVELOPMENT, DOCUMENTATION AND REVIEW
K. M. Portier, A. B. Bottcher, T. R. Hintz, W. E. Kunkle*
Computer software designed for food and agriculture applications involves
a considerable amount of time and effort. Faculty who engage in software
development need to have some idea of what constitutes quality software and
the mechanisms for obtaining appropriate credit for their investment. The
objective of this document is to provide guidelines to facilitate both
software development and the subsequent review process.
Software for the purposes of these guidelines will be defined as any
computer program which will be released by IFAS for public use through the
county agents, directly from extension specialists or the software distribu-
tion unit. Software developed for instruction or specific researcher purposes
and not intended for public use are not covered by these guidelines.
This document is divided into three sections. The first section out-
lines, in general, the software development process as well as describing the
types of documentation needed for peer review. The second section provides
guidelines for the actual structure and coding of the software. The final
section describes the peer review process which must be completed prior to
software distribution. The objective of this process is the creation of
correct, maintainable software which answers important problems.
*Asst. Professor, Department of Statistics; Assoc. Professor, Asst. Professor and IFAS Computer Network Mgr., Department
of Ag. Engineering; Asst. Professor, Department of Animal Science; respectively, University of Florida, Gainesville 32611.
I. GUIDELINES FOR SOFTWARE DEVELOPMENT AND DOCUMENTATION
Software development includes both the computer program design and the
documentation of that design. Program design results from a well structured
process which involves first problem assessment, then the determination of
processes important to solving the problem, and finally the writing and
debugging of the actual computer code. Documentation of both the development
process and the program itself will allow reviewers and users to evaluate the
software's appropriateness and reliability. Guidelines for the actual coding
and internal documentation of the computer program are given in the next
The following outline details the software development process. This
same outline presents the major items which should be present in the docu-
mentation which accompanies the software into peer review.
A. General Information
1. Statement of problem. The problem being addressed by the software
and potential users of that software should be clearly and concisely
stated. The problem should be identified with priorities determined
through the sponsoring unit's planning process and meet an identi-
fied need. The specific objectives of the software should be
spelled out, particularly from the end user's perspective.
2. Justification. Justification should include items such as:
audience expected to use the software, the potential economic
impact, degree of usage anticipated around the state, transporta-
bility of program either within state or out of state. In short,
what are the benefits to Florida users? Also address why computer
presentation is better than other approaches.
B. Scientific and Technical Information
1. Review of previous work. A detailed review of existing work needs
to be done to assure that appropriate methodology and technology are
being used to address the problem. This should include a review of
ongoing research, published research, and related software develop-
ment efforts. Theories or algorithms related to the project should
be well researched, referenced, and documented.
2. Software's Problem Solving Procedure
a. Methods selected. This would include the algorithms and
specific equations which are used within the software to
provide the necessary results. Solution methodologies could
include anything from analytical to statistical approaches.
Regardless of the approach, some diagram illustrating the
software logic and analytic processes should be included.
b. Data files. The general procedure that algorithms within the
program use to manipulate external data files needs to be
documented. Specifically, it must be explicitly stated how
data files are accessed and the types of data expected within
these files. Sources used to obtain the.data should be given.
Input and output formats should be described so updates and
changes can be made to these files.
c. Variables and parameters. The variables and parameters used
within the software need to be listed and defined.
d. Inputs and outputs. A general description of the required in-
puts and the produced outputs need to be listed for the pro-
gram. This will include the file description, the default
values, the interactive inputs required by the user, how such
inputs will be checked for acceptability and how errors in
entry will be handled. Graphical output should be carefully
considered because of potential hardware compatibility.
e. Assumptions and interpretation. This is probably one of the
most important areas of documentation and program design. The
actual assumptions which were used within the software need to
be specifically pointed out because of their potential impact
on related applications. The reason the assumptions were
selected and an interpretation of the potential results need to
be spelled out in detail.
C. User Information
(The User Manual). This is a self-contained section of the documentation
in which the specifies of the program are given in sufficient detail to
allow the end user to make ready use of the program. This would usually
be the only documentation released to the user. In general, the user's
manual would be structured as follows:
1. Introduction and Background. A brief history and background as to
why this software was developed should be given. Also, it should be
clearly stated where, when, and how the software is intended to be
used. This section should include a brief description of the
algorithms and theory on which the software is based, a general
description of information required of the user to use the software
and what he or she can expect it to give them. This includes a
description of expected results and their potential limitations.
2. Annotated example run. The user manual should have a documented
step-by-step procedure for using the software. An example run with
necessary inputs and resulting computer responses is required to
allow the first-time user a detailed guide through the program.
This example run must have all the required key strokes and infor-
mation or data necessary to complete the example run. Computer
responses and computed results should be given to allow ready
evaluation by the user and to verify that the program is working as
expected. Entire screen displays are preferable to displaying
single lines when illustrating the example.
3. Interpretation of results. A precise procedure for interpreting the
software's output should be given. This is particularly important
when interpretation is not included within the program. Examples
and explanations should be provided so that the user can interpret
the program results and be able to incorporate them into actual
decision processes. As much of this as possible should be put
directly into the software. Any cautionary notes as to the limits
of the use of the program or reliability should be given in this
4. Optional information. Source listings, program flow diagrams and
other technical details of the program will usually not be included
in the user's manual but may be included when it seems appropriate.
D. Program Test Documentation
This section is needed to facilitate the review process. Reviewers need
to be confident that the software is reliable for handling user misuse
and providing correct results under numerous conditions. The software
needs to be fully verified by comparisons to actual data or other
computational methods. These procedures need to be documented for the
reviewer. In addition, an analysis of the sensitivity of the results to
different parameter values should be done when appropriate.
1. Analysis and testing. This should include the entry of erroneous
data and its detection by the program in order to assure misleading
results are not generated. The person who actually does the testing
and when the testing was done should be recorded. Refer to Part II
for details on the program development and testing process.
2. Follow-up program. It should be shown how a follow-up evaluation on
the software's performance will be carried out. This should include
a survey of future use and user acceptance, particularly for the
problems incurred. How these problems would be addressed should be
Acknowledgements should be given to staff, support personnel and techni-
cal information sources which were used during the process of developing
the software. The acknowledgements would be similar to those used in any
published work and are strictly up to the author's discretion.
The bibliography should reference materials used in determining the
theory, algorithms, and techniques in the software development itself.
Citing of literature within the documentation should be done at all
points where appropriate.
II. GUIDELINES FOR CODING AND INTERNAL DOCUMENTATION
Basic principles for the design and programming of computer software have
evolved over the last 20 years. These principles have developed to help
reduce the cost and maintenance associated with computer software. This
section is intended to help faculty and staff utilize these concepts in the
design and coding of software for eventual release to the public. Each stage
of the software coding process is discussed and recommendations are made for
the management of typical problems.
A. Project Initiation
1. Problem statement. A good design is possible only if a good
description of the purpose, scope and required results of the
envisioned software is available. By completing parts I.A and I.B
all information for initiation will have been obtained. Part III.C
on Review Criteria also contains information on the quality of the
end product necessary to pass review.
2. Cost estimate. Estimate of the funds, equipment, manpower and time
requirements to complete this project are needed and should be
compared to available resources and the expected benefits of the
Once functional requirements of the software are known, a detailed
description of the internal structure of the software should be written.
This provides a framework within which a programmer can implement the
design. Experience has shown that the majority of software flaws and
errors observed in final testing can be traced back to mistakes and
shortcomings in the design phase. In the long run it pays to spend
time in writing out detailed specifications.
1. Operating system. Careful consideration should be given to the
selection of the computer type, operating system and programming
language on which to implement the program. A program written for
general distribution should be able to run on a number of types of
computers. Since few standards exist for operating systems and
programming languages, some modifications will be necessary each
time the initial program is migrated to a new computer. A good
program design will attempt to reduce the amount of modifications by:
a. Using operating systems and programming languages which are
available on a number of micro's and have uniform filing
and data management procedures.
b. Using sparingly the special hardware features of the
computer, such as special graphics and file handlers. When
these features are used they should be implemented in separate
modules or subroutines which can be replaced when the program
is moved to another system.
2. Program flow. Although program design is not a rigorously formal
procedure, a number of programming tools and methodologies are
available to aid in creating a good design. These include:
a. Modularity in program design. A 'module' is an identifiable
subportion of a program that usually performs one or a few
related tasks (calculations, input data, output information,
etc.) Modules should be kept small and be simply and easily
understood. Use separate service modules to handle all input
and output and, in particular, to manipulate data bases and
handle any special hardware features.
b. Information-flow diagrams. Use diagrams to identify modules
and the flow of information among these modules.
c. Hierarchic decomposition. The problem to be solved is broken
down into a number of tasks and these into subtasks until the
complex problem has been decomposed into a number of simply
understood modules. These modular subfunctions can then be
programmed, tested individually and finally combined to provide
the solution software.
3. Diagnostics and error detection. Software written for general dis-
tribution needs to be as 'foolproof' and user friendly as possible.
This suggests that program design should account for the many and
various ways a user will provide invalid responses to program
queries. Include modules to check input data against established
acceptance ranges and critical computations for appropriateness.
The program should control all means of termination and print
meaningful diagnostic messages as to what vent wrong. Accidental
termination of the program that results in loss of inputted infor-
mation should be prevented. The use of online HELP is strongly
encouraged. This allows the novice user to easily obtain the
information needed to successfully run the program while allowing
the experienced user to proceed rapidly to get the program results.
Help can be provided as a menu item, in response to a command or as
the result of a program perceived error.
4. Test strategy. As the design specifications for the program are
developed, criteria to test whether the final program meets these
specifications must also be recorded. Test inputs and data sets can
be decided upon at this time and designed so that all of the criti-
cal logical paths of the program are examined.
5. IFAS Requirements. Programs to be distributed under the auspices of
IFAS will be required to have an entry screen which contains the
a. Descriptive program name.
b. IFAS Logo.
c. Copyright notice.
d. Program number and version number.
e. Date of release.
On this first screen there should be an initial menu which allows the user
the option to view program credits. The credit screens should display:
a. Original source of program if not within IFAS, and revision
b. Authors and programers of software and/or modifiers of
c. Individual to contact with questions about software.
d. Sponsors of the software, if any.
e. Brief abstract of software.
f. Special software and/or hardware requirements.
Given the detailed design specifications, actual programming or coding
of the modules should be straightforward. The following guidelines are
offered to aid the coding process.
1. Language. Use a high level programming language (BASIC, PASCAL,
FORTRAN, etc.) unless otherwise required to meet specific design
specifications. This reduces the effort needed to maintain and
modify the program at some later date.
2. Structured programming. Use the concepts of structured programming
as much as possible. Structured programming advocates the use of
control logic structures consisting of sequence, two-outcome
decisions and restricted looping. References for structured
programming are included in section II.E.
3. Internal documentation. A detailed description of the internal
components of a program are of major importance to the maintenance,
modification and useful lifetime of an application. Both comment
statements within the program code and supporting textual informa-
tfon must be developed.
a. The actual computer code should contain enough internal
documentation (comment statements) to allow the programmer and
associates to determine easily the function of the particular
program segment or module. Clean and concise code is the most
important documentation. Comment statements supplement this
code by identifying program elements and processes.
b. Supporting text documentation must be provided to help future
programmers understand specific program features that may not
be readily apparent by looking at the code. Features that
should be listed with as much detail as possible are variable
definitions, subroutine functions, data file requirements and
descriptions, modification history, flow charts, memory
requirements, and other information unique to the program.
This should be a separate document that could be distributed
with the source listing of the program. It is not intended for
distribution to general users of the program. Some of this
documentation could be provided on a separate floppy disk or
cassette tape for those users who want it.
4. Menu construction. Menus and other questions are the interface
between the program and the user. Careful attention should be paid
to the actual wording of questions to ensure that a valid response
is obtained. Multiple choice questions (menus) allow the program to
restrict responses to some approved range and thus provide better
error control. The user should be able to gracefully exit the
program from any of these menus.
D. Testing and Validation
A strategy for final testing and validation of the software during coding
was agreed upon in the design phase. This involves testing each module
as it is completed and again as it is integrated with other modules to
make the full program. Test inputs, and data sets should be available to
examine the complete range of possibilities for the program to ensure the
reliability of the final product. Testing methodology and final test
results are to be included in the documentation used in the software
review process. The use of two testing strategies are encouraged. These
include the use of example cases that illustrate usual and unusual appli-
cation of the software as well as sessions using individuals from the
projected user group (foresters, beef producers, small farmers, ...).
Try to avoid use of arbitrarily chosen tests that do not clearly exercise
previously untested functions and logic.
This is a list of basic references on the design and coding of computer
software. Any good book on this subject will provide guidance in deve-
loping a quality software product.
1. Standardized Development of Computer Software; Robert C. Tanswathe;
Prentiss-Hall, Inc., Englewood Cliffs, New Jersey, (1977).
2. Software Reliability; H Kapetz; Springer-Verlag New York Inc.,
3. The Elements of Programming Style; Kennigham and Hlouger; McGrawr-
Hill Book Company, (1974).
III. GUIDELINES FOR SOFTWARE REVIEW
The purpose of a peer review of any program to be released for public
use is to assure a high standard of quality of software and associated documen-
tation. Characteristics of concern include originality, appropriateness of
methods, accuracy, validity, organization and clarity of documentation.
The following outline details the materials and methods of the software
A. Documentation Requirements
1. Software design documentation. A document which follows the
Guidelines for Software Development and Documentation (Part I) is
the primary source of information for reviewers. It contains the
scientific and technical information needed to perform a responsible
evaluation of the software. Included in this documentation is all
of the information outlined in Section I and the self-contained User
2. Source code. A printout of the computer program as well as a copy
on the media (diskette or tape) to be used for distribution are
required for review.
B. Software Review Committee
Review of software rests with the Chairman of the department primarily
responsible for its development. The responsible Chairman will arrange
for peer review of the software before approving the program for
publication and release. This review should include faculty from within
and outside the initiating department, as appropriate, to insure that
both content and technical aspects of the software are examined.
Software review committees should arrange for a copy of all materials
(software and documentation) to be sent to the Software Communication and
Distribution Section (Editorial Department) for technical evaluation.
After completion of the review and approval by the Chairman, the
program will be forwarded to the appropriate Assistant Dean, Research or
Extension, for sign off.
The Assistant Dean will send the draft document to Editorial for
editing, lay out, nurmbering in appropriate series and printing. A copy
of the approved publication request form will be provided to the Software
Communication and Distribution coordinator.
C. Review Criteria
1. General criteria. The review process follows the general guidelines
for review of any publication. What is examined is the appropriate-
ness of the problem, adequacy of the software and the completeness
of the documentation. In addition, computer software written for
general use must be a reliable, maintainable, user friendly and
credible product. The following criteria address some of these
specific items to be examined.
a. The problem. Is the problem appropriate for computer applica-
tion? Is there a generally acceptable methodology for solving
the problem? Is this problem of such magnitude or utility to
justify a computer program for its solution?
b. The software. Does the software correctly implement the
solution methodology? Are program 'menus' understandable and
adequate (user friendly)? Does the software recover from
errors in such a manner that a minimum of information is lost
and the user knows what should be done next? Can the software
be maintained? Is internal documentation adequate?
c. The documentation. Does the Design Documentation clearly state
the objective and solution methodology of the problem? Are the
limitations of the software clearly stated? Does the 'Users
Manual provide enough information to understand and use the
software? Are sample runs included to enable the user to test
the software prior to actual use? Are examples given which
clearly describe and interpret the output?
d. Education. What level of user education is required to use
this software? Is the information needed to run the software
readily accessible to the user?
The Published Documentation will become a part of the computer technical
publication series with copies sent to the technical library and other
software support staff. This documentation will serve as the document
of record for resumes, achievement reports, tenure and promotion docu-
ments, etc. A distribution packet will be produced composed of the
Users Manual and computer media (diskette, tape.) This will be presented
to the Software Communication and Distribution Section or IFAS Computer
Network for distribution. Editorial will supply notification copies of
the completed publication to the author, software coordinator and
appropriate Assistant Dean. The remaining supply will be shipped to
publications distribution for storage and handling.
Many individuals have helped in the development of these guidelines. He
would like to thank the members of the I.F.A.S Computer Users Committee for
enlightened evaluation and discussion of the early drafts of this paper.
Specifically we acknowledge the help of J. F. Cunnings, C. J. Wilcox,
D.C. Herzog and T. A. Wheaton of the committee and J. T. Woeste and G. L.
Zachariah of the Computer Policy Committee.
COOPERATIVE EXTENSION SERVICE, UNIVERSITY OF FLORIDA, INSTITUTE OF FOOD AND AGRICULTURAL
SCIENCES, K. R. Tefertll~er, director, In cooperation with the United States Department of Agriculture, publishes this Infor-
mation to further the purpose of the May 8 and June 30, 1914 Acts of Congress;and Is authorized to provide research, educa-
tional Informaetion and other services only to individuals and institutions that function without regard to race, color, sex or
national origin. Single copies of Extension publications (excluding 4-H and Youth publications) are available free to FlorlIda
residents from County Extension Offices. Informaltion on bulk rates or copies for out-of-state purchasers Is available from
C. 19. Hinton, Publications Distribution Center, IFAS Bulidingl 664, University of Florida, Gainesvlle~, Florida 32611. Before publicizing this
pub~lction, editors should contact this address to determine aIvalalbility.