Program Design

P. Juliff

Chapter 1: Introduction to Software Development

1. Amateur vs. Professional Programming

Amateur software development is primarily concerned with producing a correct solution to a problem
for the individual programmer. The elegance of the solution may not seem important and
documentation may seem to be unnecessary as the author will be the programs sole user.

Professional software development, on the other hand, involves, in most cases, large and complex
systems to be operated and maintained by the people other than the original author. It may last for
many years during which time it will be continually enhanced and amended to meet the changing
environment in which it operates. The elegance or style with which the software is written and clarity of
its documentation will be more enduring than the correctness of its solution.

2. Some assertions about the Software Development

The important points in the software development activity:

The development of software is an inherently difficult and demanding task.

Coding, the expression of the solution in a particular programming language, is only one small
facet of the development task and not the most important one.
Programming is a discipline to which certain principles may be applied, independent of
computer type, language or application.
There are objective criteria for good programs it is not a matter of personal aesthetics.
Despite the appearance of correctness of solution as the prime criterion in judging a program,
its style and structure are of more enduring importance.
Given that programs process data, an understanding of the nature and structure of data is
essential prerequisite to the development of software.

Professional programmers should be aware of as many techniques and practices as possible and be
able to select an appropriate solution for the problem from a number of possibilities. There is seldom
only one way to solve any software problem. The choice depends on working environment of the
software and level of expertise of the staff, who will operate and maintain the software.

3. Tools for Program Design (its need??? Plain words)

The notations used for algorithm specification must conform to a basic set of criteria:

It must be concise: We must be able to describe the solution to a problem without writing
multiple pages.
It must be unambiguous: (to be operated by a machine with no common sense).
 It must be capable of machine execution: The action described must be capable of translation
into precise, machine-executable operations.
It must promote elegance in the solution: The tool must prevent the programmer from using
practices at the design stage which lead to poor programming style during implementation. A
good design tool will lead to programs which are elegant in their design, accurate in their
operation and easy to amend and enhance over a long period of time.

4. A short history of software design

Programming as an Art Form

When programming emerged as an activity some forty years ago, the main preoccupation was the
correctness of the solution. Precisely how that solution was derived was very much subordinate to the
actual solution itself. The design tool that emerged from this period was the flowchart. To some extent,
they provided a means of depicting the program structure, but their main concern was with logic flow.
This reflected the contemporary view that programming was mainly concerned with logic.

Modular Programming
In the early 60s, program designers stressed the importance of decomposing a problem into smaller,
self-contained tasks. Each of these sub-tasks, or modules, or procedures, could then be considered
individually. If necessary, they would be broken up into yet smaller tasks. This process of top-down
decomposition would continue until a level of task is reached which perform a single, well-defined and
understandable process.

These tasks could then be removed, relocated, amended and replaced as the need arise without causing
any major disruption to the program as a whole. The process also had the effect of concentrating all of
the operations related to any task in a single module rather than have them scattered among other
functions within the program.

Modular programming was the beginning of a departure from regarding logic as the most important
aspect of software to an admission that the structure of a program was at least as important as its logic.

Structured Programming
Around 1960s, from the various publications on the way of programming, the term structured
programming was coined to describe a body of technique incorporating and formalizing these
concepts.

Two design tools emerged from structured programming:

Nassi-Shneiderman (NS) diagrams

NS diagrams appeared in an attempt to overcome some shortcomings of flowcharts. They are essentially
flowcharts without the necessity for arrows to indicate the flow of logic. The arrow symbols in
flowcharts allow programmers to design solutions which do not conform to the structured programming
concepts of sequence, selection and iteration. Flowcharts which break these rules may be implemented
in programming by the use of branch (Go To) instructions resulting in a consequent loss of control over
the program structure.
 Pseudocode
Pseudocode, sometime referred to as Structured English, is a text-based tool rather than a diagrammatic
one. It requires an algorithm to be specified with the same precision as that of the programming
language in which the program is eventually written. To that extent, it has syntax rules which have to be
remembered and adhered to. By moving from diagrams to text, pseudocode brings the design process a
step closer to the coding process and makes the ultimate translation of the algorithm into a
programming language somewhat easier.

Object-Oriented Programming
Object-oriented programming (OOP) is an emerging major programming paradigm. An object is a
particular instance of a class and consists, essentially, of data which defines its characteristics and
current status together with procedures, or methods, which operate on the object.

5. Tools for Algorithm Specification

Flowcharts
[It is a diagrammatic representation of the flow of logic within a program or within an individual process.
Their main concern was with logic flow.]A flowchart is a diagrammatic representation of the process
involved in arriving at a solution to a problem.
While many symbols are included in its notation, the most important are:

Symbol Meaning
Rectangle Process or operation
Diamond decision
Two horizontal parallel line Terminator
Arrow flow of logic

Nassi-Shneiderman (NS) Diagrams

Like flowcharts, NS diagrams are a pictorial representation of the flow of logic within a program. As
stated earlier, the removal of the necessity to use arrows to indicate the flow of logic prevents the
possibility of non-structured constructs being incorporated with a program design.
The symbols used in NS diagrams are;

Symbol Meaning
Rectangle Process or operation
decision
Multiple Selection
Iteration
A called sub-procedure

The flow of logic is indicated by joining the symbols together so that the steps are executed by
proceeding from top to bottom.
Pseudocode
The purpose of the pseudo code is to provide a means of specifying algorithms which is independent of
any particular programming language. Its purpose is to provide a means of being able to specify the
solution to a problem in a form which is:
Precise: the writer and all subsequent readers will understand exactly what is required to be
done;
Concise: it removes the necessity for verbose, easy-like instructions containing language which
is often vague or ambiguous; and
Language independent: the reader is free to implement the algorithms in the syntax of any
chosen procedural programming language with similar features.
 6. Comparison of Design Tools
Flowcharts
For
The flow of logic is easy to follow
Many people find diagrams easier to follow than text
Good for simple procedures
Against
Because arrows can be drawn from anywhere to anywhere, the flow of logic can become
convoluted unless strict discipline is enforced.
Cumbersome for complex procedures
Difficult for computerized construction and amendment without using drawing tools
Poor in illustrating program structure
No provision for data definition and scoping

Nassi-Shneiderman (NS) Diagrams

For
Essentially the same benefits as flowcharts with the advantage that the absence of arrows
ensures strict adherence to structured programming concepts.
Against
The same restrictions as for flowcharts
The real case against NS diagrams is that nobody really uses them as design tools.

Pseudocode
For
Approximates the format of a programming language and is therefore easier to be translated
into a program than are diagrams
Easier to computerize because it is held in text format, and can be constructed and amended by
a word processor.
Allows for the definition and scoping of data
Enforces adherence to structured programming concepts by not providing features which would
enable their transgression.
Universally accepted as a basis of algorithm specification in the absence of a specific
programming language.

Against
Some people find text harder to understand than a diagram
While it is a good vechile to design logic, it is poor for designing structure.

7. Conclusion
One of the distinguishing characteristic of any professional is the amount of care and preparation which
they bring to their work. Writing any but the most trivial software requires a professional approach to
the task.
Chapter 2: Problem Solving

1. Introduction
In simple terms, a program is a series of procedures designed to process data and produce result
according to a problem specification.

These procedures may be simple and relate to everyday activities such as computing electricity bill,
reservation system, pay slips, etc, or they may be complex and require precise mathematical
computations like, for example, to place a satellite in orbit. In either case, the processes are the same. It
is only the scale (and of course, the consequences of a mistake) which differ.

Programs are common in the sense that they must have structure, a means of describing the data on
which they operate and a means of manipulating that data.

Procedure-driven programs are the programs where the program coding directs the sequence of
events.
Event-driven programs, such as those operating under Windows, have a physical structure but no
logical structure. The procedures of these event-driven programs may be regarded as independent sub-
programs executable on the operators demand. The process involved in designing these individual
procedures, however identical.

2. Problems and their Solutions

The steps involved in the development of any program are:
1. Understand and define the problem.
2. Construct a program design document or blueprint from which the program can be coded.
3. Write the program code in a suitable programming language.
4. Convert the coded program to a form which can be executed by the computer. This process is
often referred to as compiling the program although many programming languages can
execute without compilation.
5. Test the program with data designed to detect any errors in its operation.
6. Prepare whatever additional documentation is needed to facilitate its comprehension and
maintenance over a period of time.

The ability to write programs to solve problems depends on the ability to solve them with pencil and
paper.

We cannot write a program to solve a problem which we do not understand or which we have not
defined in sufficient detail.

Problem
Compute the average of the following set of numbers: 4, 16, 8, 3, and 19. (Standard deviation?)

The pencil and paper solution to the problem can be expressed as a series of steps:
1. Add the numbers to obtain their total (50)
2. Count the numbers (5)
3. Compute the average by dividing the total by the count. (10)
Even in this trivial example, the point to understand is that the programmer must be able to solve the
problem manually, in order to be able to describe the steps involved in the solution.

Note that it is not necessary for the programmer to understand what the standard deviation is, just how
to calculate it. This is the fundamental difference between the programmer and the client. The client,
presumably, has knowledge of the problem domain, and is able to interpret the result produced by the
program.

While the knowledge of the problem domain is not essentially required for a programmer to be able to
write a program, the programmer is strongly advised to acquire at least sufficient knowledge of that
domain, to have a feeling for the work being done within the program and subsequently, for the
accuracy of the results which it produces.

3. Producing a program
To an extent, the three steps given above to compute the average of a set of numbers constitute a
program which another person could replicate and follow even though they did not understand what
they are doing. This clearly is the first essential of any computer program because a computer obviously
has no understanding of what it is doing. It merely follows the procedure, be that procedure right or
wrong.

(Obvious is not so obvious to computer)

In order to convert a human program to a computer program, we need precision on a scale not required
for the human processor. For example,
Where do the numbers come from?
If the numbers are to be input one at a time?
Does it matter if the numbers are a mixture of positive and negative values?
How big are the numbers to be?
How is the answer required to be given?
What should the answer be if the program is executed and no numbers are supplied as input?
Is the answer to be displayed on a screen, printed, or written to a magnetic file?

It is this precision which we must learn to bring to our solutions to problems when we convert them
from pencil-and-paper expressions of the steps involved to a program which could then be coded in a
programming language and executed by a computer with the expectation of achieving a correct result
every time the program was executed regardless of the data input during execution.

The ability to understand and express this precision is an essential skill in software development.

The procedure required for a computer to solve a problem is referred to as an algorithm.

The algorithm must:
Arrive at a correct solution within a finite time,
Be clear, precise, unambiguous, and
Be in a format which lends itself to an elegant implementation in a programming language.
 4. Control Structure
The key to elegant algorithm design lies in restricting the control structure to the three basic logic
constructs defined by the structured programming paradigm. The three basic control structures
illustrated by the pseudocode are:

Sequence: A series of instructions executed one after the other.

Selection: A choice between a numbers of alternative courses of action.
Repetition: A sequence of operations repeated for a number (which could even be zero) of
times.

5. Types of Program Statements

Here we will examine the types of statements usually found in programs.

Program statements or instructions, can be classified broadly into two groups:
Non-executable and
executable

Non-executable statements
These are statements written by the programmer for the guidance of the compiler or to enable
subsequent programmers understand the program. These statements do not require any action when
the program is executed. The most common types of such statements are:
Procedure definition
Data definition
Comments
It is essential that programmers realize that their programs will be read by other programmers.
Programs are in a continual state of change in an operational environment due to the changing nature
of their users requirements. It is imperative that maintenance programmers be able to make changes to
operational programs quickly and reliably. This depends both on the elegance of the original program
and on the ability of the maintenance programmer to readily understand what the program is doing.
The inclusion of comments by the original programmer and, of course, by the subsequent maintenance
programmers is an important component in this comprehensibility factor of programs.

Comment lines in our pseudocode commence with a # character.

In short, the non-executable statements form a pattern which will be repeated in all programs.

Executable Statements
These are the instructions to be executed when the program is running.
 Arithmetic operations
Assignment of value
Sequence control
Program instructions are executed in the order in which they are encountered as the program
executes.
Selection
Multiple selection
Repetition
Termination
The execution of a program will continue until it is told to stop.
Procedure calls
A procedure calls occurs when one procedure, the calling procedure, requests the execution
of another procedure, the called procedure.
Input and output

Patterns of Logic
Two very basic patterns of logic to identify in most programs are:
Beginning-middle-end
Input-processing-output

Conclusion
We have seen that a program is, in essence, a formula or a recipe to follow to produce a correct solution
to a problem. The essentials are that we understand the nature and the extent of the problem, that we
could compute the result in pencil-and-paper mode if we had to, and that we express the solution in a
precise, unambiguous manner. This precision is required if others are to follow our instructions and
obtain the correct result, particularly if the instructions are to be converted into a programming
language to be followed by a computer.

The method used to specify these programs or algorithms is a pseudocode which has the formal rigour
of a programming language, and which can then be translated into any of a number of programming
languages to be executed.
Chapter 3: Problem Solving Complex Procedures

1. Introduction
In the previous chapter we looked at procedures which were specified in terms of structured
programming constructs of sequence, selection and repetition.

2. Nested Selection
Nested selection occurs when a series of if..then..else..end if statements are placed one within another.
In such a case, it is essential to ensure that the respective if and end if statements match.
The indentation formatting ensures this matching process. Indentation is merely cosmetic.

3. Compound Selection
Compound selection occurs when an if is required to evaluate a number of conditions connected by one
or more combinations of andandor. A further complication arises when negatively expressed tests are
made using not in addition to andandor.

The following are possible compound selection which may be needed in a program to determine
whether or not this employee meets certain criteria:

Is the employee a male aged between 20 and 30 inclusive

If Gender= M and Age>= 20 and Age <= 30

It is useful to remember De Morgans Laws relating to the negation of compound conditions.

Simple stated, they are
Not(X or Y) is equivalent to not X and not Y
Not (X and Y) is equivalent to not X or not Y

4. Multiple Selection
Multiple selection involves the testing of a data item to determine which one of a number of possible
values it contains, or whether it contains none of those values at all. It is possible that each value which
could be matched would have its own procedure to be executed as a consequence.

Simple Calculator (+, -, *)

If operator = + then
A+b
Else
If operator = - then
a-b
else
if operator = *
a*b
else
operator Error
end if
 end if
end if

A more elegant method of accomplishing such a procedure is with the use of the case statement.

Case of operator
+ : a+b
- : a-b
* : a*b
Else : operator error
End case

A case statement is also useful in testing ranges of values

5. Nested Repetition Structures

A nested repetition structure consists of loops within other loops. The general structure of such
procedures is
while
statement(s)
while
statement(s)
while
statement(s)
end while
statement(s)
end while
statement(s)
end while

Theoretically, loops may be nested to any level. In practice, however, nesting them more than two or,
at the most, three levels deep would mean more complex logic. If deeper nesting is required, it is
preferable to remove the inner loops to separate procedures.

6. Conclusion
As we progress towards the solution of more complex problems, the necessity for careful design
becomes more important. The formatting of written code using levels of indentation becomes essential.
However, we must avoid the temptation to write increasingly long and complicated procedures. It will
become necessary to break up complex processes into smaller, easily understood components.
Chapter 4: Introduction to Sub-procedures

This chapter introduces the concept of sub-programming by explaining the reasons which make this
technique desirable.

1. Simplification of Complex procedures

The principles we are to consider now are not unique to software development. They are essentially
applicable to any large and/or complex procedure which needs to be understood by those responsible
for its accomplishment.

Class Discussion
Program 1 (Single Procedure): GradeCardGenerator

Intmain()
{
// input data
..
//Attendence
.
.
.
//Quiz
.
..
//Semester Exam
..
..
//Report
.

Program 2 (Broken into sub procedures): GradeCardGenerator

Intmain()
{
Attendence();
ClassTest();
SemesterExam();
Calculator();

ReportGenerator();
}

The aim of the list is to indicate the procedures involved and the order in which they must be done.

Providing that each group of programmers performed their allotted task in the required sequence, we
would have a project completed at the end of the procedure

We may not have any domain knowledge, despite this we can read the program and understand the
process being carried out.

From what has already been discussed of programs, it is obvious that each of the named procedures in
this algorithm will be a mini-program in its own right. It will have its own procedural instructions and,
very likely, its own data. It is conceivable that if the program were extremely large or complex, each of
these procedures could be given to a separate programmer. Each programmer could write his or her
own procedure and hopefully when they are all assembled in a single program, that program would
execute correctly.

2. Top-down Decomposition

Example: Indian Railway reservation system

Reservation
Cancellation
Status
Enquiry (Schedule)

There are several reasons why a program should be constructed from a number of separate sub-
procedures rather than written as a single procedure of many hundreds, thousands or hundreds of
thousands of instructions in a single complex algorithm. The breaking down of a large, complex
procedure into a number of smaller procedures is referred to as top-down decomposition.

The aim of this decomposition is to progressively simplify large and/or complex procedures by breaking
them up into smaller, simpler procedures. This is repeated until these procedures are well understood,
relate to a single task and are simple enough to express in program code.

3. Principles for Decomposition

The following are guiding principles for the decomposition of a program into sub-procedures.

Understandability
Apart from any of the more technical reasons, one of the main benefits of top-down decomposition is
the ease of readability of the resulting program coding, and the ability for the original programmer and
for others who follow him or her to be able to understand the nature of the operations of the program.
Clear Identification of Tasks
Each procedure should perform one, and only one, task and its name should be indicative of its function.
If a program is constructed as a single procedure of many hundreds of instructions and asked to make a
particular change, where would you start? You would be faced to recognize some instruction or group of
instructions which looked as though related to the given task.

Possibility of Parallel Development

Many programmers are involved in the development of a large project. The only way this can be
accomplished is to divide the project into small, self-contained procedures and allocate the procedures
among the programmers. For this to work, each programmer must understand exactly what must be
done within each of their procedures. This in turn, means that each procedure will need to be
accompanied by a precise specification of its operation and the means by which it communicates with
its surroundings.

Eliminate Duplication of Coding

No task should be coded in more than one place in any program. The reason for avoiding multiple
replications of any piece of coding are:
The obvious saving of time and efforts in avoiding the repetition of the task;
There is a likelihood that one or more of the repetitions will contain an error, resulting in the
task being done correctly in some places and incorrectly in others; this type of error is
particularly likely in cases where several programmers are involved;
In the case of a necessity to amend the procedure there should be only one place to effect the
amendment; in case of replicated code, there is chance that programmer miss some
replications.

Ease of Maintenance
Programs in an operational environment are in a continual state of change. As explained previously, one
of the key factors in enabling a maintenance programmer to effect a program amendment is the ability
to locate a single, clearly identifiable procedure which contains only the function which needs to be
amended.

Code Reusability
One of the most sought-after goals in software development is that of reusable software. This implies
that a process which has already been coded and known to work correctly in one program can be copied
into another program which requires the same function to be performed. One of the ways in which this
code reusability can be promoted is by requiring programmers to use procedures which already exist,
rather than creating new versions of a procedure and by enforcing a series of standards which ensures
that code will be transportable across a number of programs.

4. Program Structure
Since we shall be constructing a program from a number of separate procedures, it will be useful to
consider the ways in which we may define the physical structure of the resulting program. A program
normally comprises one or more controlling or manager procedures, in addition to a number of
supporting, task-oriented sub-procedures. It is common to refer to this hierarchy of procedures as
superordinate or calling procedures and subordinate or called procedures. The sub-procedures may be
included within the structure of their manager procedure or may be external to it. The subordinate
procedures themselves may have supporting subordinate procedures (sub-sub-procedures) which, in
turn, may be included within, or can be external to their superordinate procedure.

5. Communication Between Procedures

Procedures communicate with one another by sharing global data and/or by passing parameters
between them. Some of the sub-procedures into which we decompose a program may be able to
operate in complete isolation from the rest of the events within the program.

Global Data
Global data is declared to be accessible by the procedure in which it is defined, and by all sub-
procedures defined within that defining procedure. Note that global data is available only to internal
sub-procedures, not to external sub-procedures. The content of the global data items does not need to
be specifically passed from the calling to the called procedure. It is automatically available to the code
within the called subordinate procedure or to any procedure which is, in turn, subordinate to that called
procedure.

Passed Parameters
Parameters may be specifically passed between a calling and a called procedure. They may perform one
of the three functions:
They may pass data from a calling procedure to a called procedure,
They may pass data back from a called procedure to its calling procedure, or
They may fulfill a two-way role and contain a value which is passed to the called procedure,
amended in some way and passed back again to the calling procedure.

Parameters are passed between the calling and called procedures by being included in the definition of
the called procedure and placed in parentheses after the name of the called procedure in the calling
statement.

Notes
Parameters must correspond in number
Parameters must correspond in type
Parameters must correspond in position
Parameters need not correspond in time
Boolean parameters must correspond in sense

Programming languages typically implement the actual mechanics of parameter passing in two ways:
Call by value. In this case, the parameter serves as a one-way conduit only, and passes a value
to the called procedure. If the called procedure alters the value in the parameter variable, the
alteration will not be transmitted back to the calling procedure.
Call by name. The parameter variable in this method acts as two-way conduit. The value
which is passed to the called procedure may be amended, and the amended value will be
passed back to the calling procedure upon return.
 6. Sub-routines and Functions
Sub-routines and functions are variations of sub-procedures which may be called by other procedures.
Their common characteristics are:
They are invoked by stating their name together with any required parameter.
When invoked, the program control passes to the called procedure, and resumes at the first
executable statement in that procedure;
When the end procedure-name statement is reached in the sub-procedure, the program control
is passed back to the calling procedure, and resumes at the next executable statement following
the procedure call;
They may themselves call other sub-procedures, but may not call the main procedure;
They may call themselves this process is called recursion.

7. Iteration vs Recursion
In chapter 3, three essential construct were discussed of which all programs are composed. They are
sequence, selection and repetition. The model of repetition most commonly found is that of iteration,
i.e., one or more instructions contained in a loop and executed while a nominated condition applies.

Iteration is sufficient to implement any repetitive operation, and some programming languages offer no
other alternative. However, recursion is an alternative model of repetition implemented in many
languages.

Recursion is the ability of a procedure to call itself. This may be done explicitly by having the procedure
execute a call to itself within its coding, or indirectly by calling another procedure which then calls the
original procedure. While there is nothing that can be done by recursion which cannot be done by
iteration, some problems lend themselves naturally to a recursive procedure.

e.g., factorial

Recursion requires different copies of algorithm, and a mechanism by which the program can trace its
return path back through the suspended copies. This is the disadvantage of recursion.

The recursion technique allows the programmer to write an extremely concise algorithm, often in a
fraction of lines of code taken for an iterative solution to the same problem. However, the penalty is
paid at run time since the resulting program will be demanding on the resources managed by the
computer during execution.

8. Conclusion
None but the most trivial programs consist of a single procedure. A large amount of skill required to
develop software consists in the ability to be able to decompose a complex problem into a number of
simple procedures, and to design the method of communication among those procedures. The
management of data among the procedures of a complex software application is as important as the
design of the coded instructions.
Chapter 6: Program Documentation

1. Introduction
The provision of documentation is one of the most neglected areas of the programming discipline and is
also one of the greatest points of separation between the amateur and professional programmer. The
amateur programmer usually writes programs which only he or she needs to understand, operate and
maintain. The professional programmer writes programs for others to use and maintain over a long
period of time.

Since the provision of the necessary documentation to support a program is not seen as a challenge or
an intellectual exercise it is seldom done or done properly.

2. Who needs Documentation?

There are three groups of people who need to refer to program documentation and their requirements
are all somewhat different:

Programmers
Once written, programs are used in their operating environment for a period which can span ten or
more years. During this time they will be subject to many alterations or enhancements to reflect the
changing requirements of the users. This task is referred to as program maintenance and is carried out
by maintenance programmers. Most programmers spend their time working with programs which were
most likely written by other programmers who may no longer be available for consultation on the
details of their code. Unless the programs were initially well written and adequately documented,
maintenance programming is very difficult task.

Operators
Amateur programmers run their own programs; professionals usually do not. In a situation where
programs are run by an organizations computer center on data which is collected, batched and run in
periodic cycles, there will be group of computer operators whose task is to manage the physical
environment of the computer equipment. It is essential that these operators are aware of the task
carried out by any program and any likely interaction between the program and the operator at run
time, (i.e., during the programs execution).

Off-line users
The off-line user is the person or section of an organization for whom a program is run and who relies on
its output for the continuance of their functions. Like programmer, the off-line user may never see the
program actually run, this task being managed by the operators. Off-line users must understand what
input they are required to provide for the program, the nature of the processing carried out by the
program and the output which they will receive. They need to be aware of any restrictions on the nature
and content of the input and any errors which may be reported on the output which they receive. They
do not need to know the precise means by which the data is processed except to understand any
limitations which may affect subsequent amendments to the programs task.
 Interactive users
In an interactive operating environment, the roles of user and operator are combined. A clerk accepting
orders over a telephone and entering their details immediately into a computer system via a terminal
needs the documentation both to initiate and manage the programs operation and to understand the
input-processing-output cycle.

3. Documentation for Programmers

The documentation required to enable a programmer to maintain a program over its life span may be
divided into two categories:
Internal Documentation
This covers the aspects of programs which are embodied in the syntax of the programming language.
The important points are:
Meaningful names used to describe data items and procedures;
Comments relating to the function of the program as a whole and of the modules
comprising the program;
Clarity of style and format one instruction per line, indentation of related groups of
instructions, blank lines separating modules; and
Use of symbolic names of constants or literals in the procedural code.

External Documentation
This category covers the supporting documentation which should be maintained in a manual or folder
accompanying every program. It is essential as changes are made to a program, its external
documentation is updated at the same time. Out-of-date documentation can be misleading to a
maintenance programmer and result in much time being wasted.
External documentation should include:
A current listing of the source program the program as written by the programmer,
including any memory maps, cross-references, and so on, that are able to be obtained from
the compilation process;
The program specification the document defining the purpose and mode of operation of
the program;
The design documentation tools from which the program was written, such as a structure
diagram depicting the hierarchical organization of the modules comprising a procedural
program or an object structure diagram in the case of an event-driven application.
An explanation of any formulae or complex calculations in the program;
A specification of the data being processed data accepted from or displayed on a screen,
items in reports, external files processed, including the format of record structures and
fields within those records; all data being described in terms of its size, format, type and
structure;
Where applicable, the format of screens used to interact with users, and of printed reports;
The test data used to validate the operation of the program;
Any special directions of importance to programmers subsequently amending or enhancing
the program; for example, restrictions on the size of tables, and so on.
 4. Documentation for Operators
Operators who are responsible for the running of off-line or batch processed applications donot need to
know precisely how the programs work. They need to know the points at which their actions and the
program interrelate, i.e., their interface with the program. (Reservation system)
Such documentation is usually contained in an operating instructions document and should cover:
The command(s) necessary to load the program into memory and to start its operation;
The names of all external files accessed by the program;
The format of all messages which the program may display to the operator during its
execution, describing the text of the message and response required by the operator;
Any options in the programs operation which require operator action to trigger at runtime
(e.g., a special end-of month run, etc)
A brief description of the programs function so that the operator can obtain a feeling for
whether or not the program is behaving correctly;
Any technical details relating to the equipment being used (e.g., a minimum amount of
memory space required for execution, a minimum number of pheripherla or file storage
capacity).

5. Documentation for Users

As in the case of operators, users are concerned more with how they interact with the program and
what the program does for hem than the technicalities of how the program goes about its tasks.

All programs or collections of programs comprising a composite system should have a users manual.
This document follows more or less the same path as that of operating instructions except that the user
will not normally be as concerned with equipment technicalities as will the operator.

The users manual should cover:

A detailed description of the function performed by the program;
The means by which the user supplies data to the program to be processed, covering the format
and content of the data together with any restrictions on values included, and so on;
A detailed description, preferably with examples, of any output produced by the program for
the user;
Details of any error messages or exception reports which the program may produce explaining
precisely their impact on the users and any subsequent action required on their part;
Details of any options to be exercised by the user, including the implications of each option and
the means of selecting each option; and
Any restrictions on subsequent amendments or enhancements to the program, to enable the
user a realistic appraisal of the prospective usage of the program.

As with any technical report, the users manual should be clearly presented, simply explained and
indexed to facilitate its use by its target audience which will usually consist of non-technical staff who
may have only a rudimentary understanding of the nature of a computer system.
 6. Conclusion

Whatever the means employed, it is essential for both the day-today operation of a software product
and for its maintenance over its lifetime that complete documentation be created at the time of
inception of the application and continually maintained.