Procedural Programming C_ITPP111

Compiled by Yemi Adeniji

Quality assured by Kizito Matamera

Edited by Barbara Wood

Version 1.0

January 2013CTI EDUCATION GROUP

UNIT 1 - INTRODUCTION 1 1.1 Course description 1 1.2 Learning outcomes and assessment criteria 1 1.3 Lectures 2 1.4 Class exercises and activities 2 1.5 Understanding the Instruction Guide 3 1.6 Icons used in the study guide 3

UNIT 2 – PROCEDURAL PROGRAMMING 5 2.1 Introduction to Procedural Programming 5 2.2 Resources 5 2.2.1 BOOKS 5 2.2.2 WEBSITES 6

UNIT 3 – MAPPING TO EBOOK 7 3.1 Purpose of Instruction guide 7 LO1 Understand the principles of procedural programming 7 LO2 Be able to design procedural programming solutions 8 LO3 Be able to implement procedural programming solutions 9 LO4 Be able to test procedural programming solutions 9

UNIT 4 – PROCEDURAL PROGRAMMING SOLUTION FOR A GIVEN PROBLEM 11 4.1 Designing a procedural programming solution for a given problem 11 4.2 Procedural Design 12 4.3.1 TIPS AND WARNINGS 13 4.4 Examples 13 EXERCISES 18

UNIT 5 – ONSCREEN HELP TO ASSIST USERS 19 5.1 Creating Onscreen help to assist the users of a computer program 19 5.2 Introduction 19 5.3 General advantages and disadvantages of on-screen manuals 20 5.3.1 ADVANTAGES 20 5.3.2 DISADVANTAGES 20 5.3.3 SOME INFORMATION NEEDED TO BE PRESENTED TO THE USER OUTSIDE THE ON-SCREEN MANUAL: 20 5.4 The classical "help" function 21 5.4.1 ADVANTAGES 21 5.4.2 DISADVANTAGES 21 5.5 Wizards 21 5.5.1 ADVANTAGES 21 5.5.2 DISADVANTAGES 21 5.6 "Helpers" 21 5.6.1 ADVANTAGES 22 5.6.2 DISADVANTAGES 22 5.7 The on-screen book type of help 22 5.7.1 ADVANTAGES 22 5.7.2 DISADVANTAGES 22 5.8 Creating onscreen help 22 5.8.1 THESE ARE THE GUIDELINES FOR ON-SCREEN HELP DESIGN: 22 EXERCISES 25

UNIT 6 – DOCUMENTATION FOR THE SUPPORT AND MAINTENANCE OF A COMPUTER

PROGRAM 27 6.1 Creating documentation for the support and maintenance of a computer program 27 6.1.1 SOFTWARE/PROGRAM DOCUMENTATION 27

6.1.2 HOW TO DOCUMENT A COMPUTER PROGRAM 28 EXERCISES 31

UNIT 7 – EXAMINATION INFORMATION AND REVIEW 33 7.1 Initial examination information 33

GLOSSARY 35

BIBLIOGRAPHY 37 Textbooks 37 Websites 37

Unit 1 - Introduction

Welcome to Procedural Programming. This unit serves as an introduction to the

course. We will provide you with a description of the course and a summary of the learning outcomes and assessment criteria.

1.1 Course description

This unit covers the following topics:

Characteristics of programming

Types of language Reasons for choice of language

Data Structures Data types

Programming syntax

At the end of this unit, the student will be able to:

Understand how the Procedural Programming course will

be covered

1.2 Learning outcomes and assessment criteria

Learning outcomes On successful completion

of this unit a student will:

Assessment criteria for pass The student can:

LO1 Understand the principles of

procedural programming

1.1 discuss the principles, characteristics and features of procedural programming

LO2

Be able to design procedural programming solutions

2.1 identify the program units and data and file

structures required to implement a given design

2.2 design a procedural programming solution

for a given problem

LO3

Be able to implement

procedural programming solutions

3.1 select and implement control structures to

meet the design algorithms

3.2 correctly use parameter passing mechanisms

3.3 implement a procedural programming solution based on a prepared design

LO4 Be able to test procedural

programming solutions

4.1 critically review and test a procedural programming solution

4.2 analyse actual test results against expected results to identify discrepancies

4.3 evaluate independent feedback on a

developed procedural programme solution and make recommendations for

improvements 4.4 create onscreen help to assist the users of a

computer program 4.5 create documentation for the support and

maintenance of a computer program.

These outcomes are covered in the content of the study units and are tested in the exercises, assignments and assessments. If a student complies with and

achieves all the pass criteria related to the outcomes, he/she will pass this

course. There will also be opportunities for students to achieve merit and/or distinction outcomes. The merit and distinction criteria are based on slightly

more advanced requirements.

1.3 Lectures

Each week has four compulsory lecture hours for all students. It is

recommended that the lecture hours be divided into two sessions of two hours

each, but this may vary depending on the campus.

Each week has a lecture schedule which indicates the approximate time that should be allocated to each activity. The week’s work schedule has also been

divided into two lessons.

1.4 Class exercises and activities

Students will be required to complete a number of exercises and activities in class. These activities and exercises may also contribute to obtaining pass,

merit or distinction criteria; it is therefore important that students are present in class so that they do not forfeit the opportunity to be exposed to such

exercises and activities.

Activity sheets that are handed in should be kept by the lecturer so that they

can be used as proof of criteria that were met, if necessary.

1.5 Understanding the Instruction Guide

Students will receive a prescribed eBook for this course. This instruction guide will be used in conjunction with this eBook and will instruct direct the student

to the correct sections of the eBook to follow throughout the course.

1.6 Icons used in the study guide

This icon represents the start of a unit.

This symbol is found at the beginning of each unit. It

outlines the outcomes for each unit.

This icon refers the student to a learning activity or

assignment in the Assessment Toolbox.

Unit 2 – Procedural Programming

At the end of this unit, the student will be able to:

Understand the Principles of Procedural programming

2.1 Introduction to Procedural Programming

The aim of this course is to provide students with an understanding of the

principles of procedural programming and to enable them to design and implement procedural programming solutions.

Irrespective of framework or delivery platform, the development of procedural

code is still at the core of many commercial application development projects. Event-driven systems and object oriented platforms all use procedural code for

the critical command content of their objects, events and listeners.

This unit allows students to become familiar with the underpinning principles of

procedural programming. Many languages have the capacity to develop procedural code and it is not important which language is chosen for this unit.

Ideally, for students who are new to programming, this unit would be

considered the starting point before progressing onto one (or all) of the many programming units. Whilst the student is not expected to develop any complex

code in this unit, the foundations will enable the development of their programming skills.

2.2 Resources

The list below contains details for supplementary reading.

2.2.1 Books

Davis, S R. 2009. C++ for Dummies. (Wiley) ISBN-10: 0470317264

McBride, P K. 1997. Turbo Pascal Programming Made Simple. ISBN 0750632429

McGrath, M. 2009. C Programming in Easy Steps (Limited) ISBN 184078363X Parkin, A and Yorke, R. 1995. Cobol for Students (Butterworth Heinemann)

ISBN 0340645520

2.2.2 Websites

http://library.thinkquest.org/27297/ www.cplusplus.com/doc/tutorial/

www.cprogramming.com/ www.csis.ul.ie/cobol/

NOTE Also, practising with programming-based organisation or internet-based open source will greatly enhance your experience vocationally

as a student.

Unit 3 – Mapping to eBook

This unit covers the following topics:

Understanding the principles of procedural programming

Designing of procedural programming solutions Implementation of procedural programming solutions

Testing of procedural programming solutions.

At the end of this unit, the student will be able to:

Understand the principles of procedural programming.

Design and implement procedural programming solutions.

3.1 Purpose of Instruction guide

The eBook given to the students are to be used in a certain way. The

Instruction guide directs and also shows the students where to find and link

each topic of every week in their eBook. This brings about the essence of Mapping to eBook.

LO1 Understand the principles of procedural programming

Content covered for learning outcome

Characteristics of programming: low-level languages; high-level languages;

generations e.g. first, second, third, fourth, fifth; programs; applications; instructions; algorithms

Types of language: procedural languages; object-oriented; event-driven;

others e.g. script and mark-up languages; simple overviews and uses.

Reasons for choice of language: organisational policy; suitability of features and tools; availability of trained staff; reliability; development and

maintenance costs; expandability Data structures: variables e.g. naming conventions, local and global variables,

arrays (one-dimensional, two-dimensional); file structures; loops e.g. conditional (pre-check, post-check, break-points), fixed; conditional

statements; case statements; logical operators; assignment statements; input

statements; output statements

Data types: constants and literals; integer; floating point; byte; date; boolean; others e.g. character, string, small int; choice of data types e.g. additional

validation, efficiency of storage

Programming syntax: command rules, variable declaration, Standards: use of

comments, code layout, indentation

Assessment criteria 1.1 discuss the principles, characteristics and features of procedural

programming

Chapter 1: Pages 1 to 22 Chapter 8: Pages 282 to 327

LO2 Be able to design procedural programming solutions

Content covered for learning outcome

Requirements specification: inputs, outputs, processing, user interface;

constraints e.g. hardware platforms, timescales for development; units; data; file structures.

Program design: tools e.g. structure diagrams, data flow diagrams, entity

relationship models, flow charts, pseudo code

Technical documentation: requirements specification; others as appropriate to language e.g. form design, flowcharts, pseudo code, structured English, action

charts, data dictionary, class and instance diagrams

Assessment criteria 2.1

identify the program units and data and file structures required to implement a given design

Chapter 2: Pages 28 to 70

Assessment criteria 2.2

design a procedural programming solution for a given problem

Chapter 2: Pages 27 to 29 Refer to Unit 4

LO3 Be able to implement procedural programming solutions

Content covered for learning outcome

Modular design: elements e.g. functions, procedures, method, widgets,

graphical user interface (GUI) components, symbols

Software structures: as appropriate to language chosen e.g. iteration, decisions, units, functions, procedures; control structures; conditional

commands

Parameters: data types, passing data, return values Scope of variables: global, local, static, overloaded results, instance

Programming: use of programming standards; relationship to program design

Assessment criteria 3.1 select and implement control structures to meet the design algorithms

Chapter 4: Pages 127 to 136 Chapter 5: Pages 182 to 210

Chapter 6: Pages 242 to 259

Assessment criteria 3.2

correctly use parameter passing mechanisms

Chapter 3: Pages 95 to 107

Assessment criteria 3.3 implement a procedural programming solution based on a prepared design

Chapter 2: Pages 39 to 42

LO4 Be able to test procedural programming solutions

Content covered for learning outcome

Mechanisms: valid declarations, debugging code, checking naming

conventions; checking functionality against requirements, error detection, error messages, compiler errors, runtime errors, in code response, dry running

Supportive documentation: test plan; test results; programmer guidance; user

guidance; onscreen help

Review: design against specification requirements, interim reviews

Assessment criteria 4.1

critically review and test a procedural programming solution

Chapter 7: Pages 268 to 276

Assessment criteria 4.2

analyse actual test results against expected results to identify discrepancies

Chapter 7: Pages 269 to 277

Assessment criteria 4.3 evaluate independent feedback on a developed procedural programme

solution and make recommendations for improvements

Chapter 6: Pages 252 to 257

Assessment criteria 4.4

create onscreen help to assist the users of a computer program

Refer to Unit 5

Assessment criteria 4.5

create documentation for the support and maintenance of a computer program

Refer to Unit 6

Unit 4 – Procedural programming solution

for a given problem

This unit covers the following topics:

Steps to follow in designing a procedural programming solution for a given

problem

At the end of this unit, students will be able to:

Understand the meaning of procedural programming

and also be able to design a procedural programming solution for a given problem

4.1 Designing a procedural programming solution for a given problem

When you sit down at your computer, whether at home or at college, did you

ever consider what it took -- planning, researching, developing, debugging, implementing, updating, etc. -- to get this machine to do what you are doing?

To design a solution for a given problem either in the procedural way of

programming or other methods, it is simply referred to as Systems development,

System development is a six-stage process or life cycle (SDLC – System

Development Life Cycle) that consists of phases, which often overlap and may

also include:

1. conducting a preliminary investigation 2. analysing the system;

3. designing 4. developing the system

5. implementation 6. Providing systems maintenance, including updating and upgrading, with

the possibility of beginning the process all over again (Williams, B.K. & S.C. Sawyer. 2007).

4.2 Procedural Design

Procedural programming is built around the concept of developing programs

based on sub tasks (also known as modules of code). The modules are called and connected by a single parent module (main program) that coordinates all

of the modules into a working solution.

Procedural programming gets its name from procedures. A procedure is a sub task that is implemented in programming languages under a variety of

language specific names (i.e. functions, procedures, methods, sub routines, etc.)

A procedural design provides an ordered sequence of actions required to operate equipment, perform a task, take a test, maintain or implement a

system. The instructions should be written in layman's terms using simple and direct

language so that an average user will understand what is needed and that the

reader receives clear information.

In order to design a program, there are essentially two steps that involve determining:

1. The program logic and 2. Program detail.

In today’s world of programming, the first step (i.e. determining the program

logic), a structure or hierarchy chart is utilised to determine program logic. As the term,”hierarchy,” suggests, it is a top-down design or approach. Within the

hierarchy are modules or processing steps in the program which attempt to identify all elements and relationships among the elements or modules that

may be required to achieve the program’s purpose. This latter “modularisation” concept breaks each operation into smaller, more

manageable and often less complex, single functions that enable separation of

development and testing activities. There are some rules that should be kept in mind in determining the modularisation, such as keeping each module to a

manageable size; each with a single function independent of the others; making sure input and output functions are “clearly defined in separate

modules;” with single entry and exit points; and making sure control is returned to “… the point from which is was ‘called’ by …” a first module.

In summary, in determining program logic in the program design step, this

“structured programming” takes a top-down approach that breaks programs into modular forms - standard logic tools are called control structures.

4.3 Steps to follow in Program design

Given a programming problem, these are the steps to follow in the design

process:

1. Write down all of the essential steps required to perform a given procedure.

2. Organise the steps into a logical, progressive sequence to achieve the

desired outcome. Enumerate each step and attach a heading, which should not be longer than three words, to easily access knowledge.

3. Draw a diagram, sketch or graph in each step, where appropriate, to visually illustrate the concept. Write down each step clearly.

4. Test your procedure to ensure that it is accurate and includes enough information to be used. Do not assume that the user has any prior

knowledge on the subject and avoid abbreviations and acronyms.

4.3.1 Tips and Warnings

Avoid creating a procedural design that is more complex than it needs to

be.

Avoid complex numbering and identification systems which confuse the reader.

Use short sentences and simple language. Avoid extraneous information that may confuse the reader.

Avoid writing multiple steps in a single paragraph; separate steps to increase clarity.

People tend to ignore lengthy procedures, so keep it simple, brief and straight to-the-point.

4.4 Examples

The questions and answers below analyse how to design a procedural programming solution to a given problem.

Question 1: Design a program to calculate the area of a circle, given that the

formula is Pi *r^2.

Solution:

Step1: We have to write down all the steps that we need to solve this given

problem (question)

We need the formula for the area of a circle , which is given – FORMULA

FOR PROBLEM The variables in the problem are to be identified, which are Area (A)

radius (r) and Pi – IDENTIFICATION OF VARIABLES Then, the values for r and Pi need to be input – ASSIGNING VALUES

The Area of a circle (A) can then be calculated using the input values -

AREA CALCULATION The result of the calculation is then displayed – OUTPUT OF AREA

Step2: A diagram to show each step above for visual illustration.

Figure 1

Step3: We need to test our program and also confirm if all the information

needed is provided

From the above steps i.e. 1 and 2: The formula to solve the given problem (Area of a circle) is provided

The variables required are all identified Values are also assigned to the input variables – Pi and r

Output variable is also calculated and result was displayed

Since the result of the given problem could be calculated (i.e. solution to the

given problem), we can therefore conclude that enough of the needed information was given.

Formula for the Area of a circle = Pi*r^2 = Pi*r*r

Question 2: Design a program that shows how an elevator performs its

tasks.

Solution: Step1: We have to write down all the steps or states that an elevator can be.

An elevator can be in Idle state (i.e. when it is not used by anybody) –

FREE STATE Another state is Move (i.e. when the elevator is working by carrying

people up) –MOBILE STATE The elevator can also be in a Stop state (i.e. after carrying people, it is

going to halt at the designated point) – ELEVATOR STOPS The elevator can then go back to either Idle state or Move state,

depending on how it is being used.

Step2: A diagram to show the possible states of the elevator for visual

illustration.

Figure 2

Step3: We need to Test our program task and also confirm if all the states are

represented properly and in the right directions.

From the diagram above in Step 2: The first state (Idle state) the elevator was waiting

Then to the second state where it is busy moving and carrying people (Move state)

It then gets to the third state where it stops ( Stop state) Depending on the availability of people, the elevator either goes back to

the Idle state or to the Move state.

The order of steps expected of an elevator has been followed and observed, it

is complete as analysis in the example above, and therefore, we can conclude that the Test has succeeded.

Idle state of elevator (waiting for people to

take)

Question 3: Design a program to calculate a person’s body mass index

(BMI). The BMI is often used to determine whether a person is overweight or underweight for his/ her height. A person’s BMI is

calculated with the following formula: BMI = Weight x 703/height2

Solution

Step1: The Design steps that we need to solve the given problem (BMI = Weight x 703/height2)

We need the formula for the body mass index, which is given – FORMULA

FOR PROBLEM The variables in the problem are to be identified, which are Body Mass

Index (BMI) Weight (w) and Height (h) – IDENTIFICATION OF VARIABLES

Then, the values for w and h need to be input – ASSIGNING VALUES The Body Mass Index (BMI) can then be calculated using the input values

- BMI CALCULATION The result of the calculation is then displayed – OUTPUT OF Body Mass

Index. Step2: A diagram showing the steps to solve the given problem for visual

illustration.

Figure 3

Formula for BMI = weight x 703/height ^ 2 =

Weight = w Height = h BMI = w * 703/h * h

The result for the BMI is displayed as output.

Step3: The sub tasks need to be tested to confirm that they are connected

and become a working solution.

From steps 1 and 2: The formula to solve the given problem (Body Mass Index - BMI) is

provided

All the needed variables are identified Variables are also assigned to represent the input variables – w and h

A constant number 703 is also used for the calculation Output variable is then calculated and the result was displayed – BMI

Since the result of the given problem could be calculated (i.e. solution is

achieved for the given problem), we can therefore conclude that enough of the needed information has been provided.

EXERCISES

ASSESSMENT TOOLBOX Learning Activity No. 4

Group Exercise No. 2

Unit 5 – Onscreen help to assist users

This unit covers the following topics:

Onscreen help in programs

Guidelines for Onscreen help design

At the end of this unit, students will be able to:

Understand the concept and importance of Onscreen help

Create user assistance and instructions onscreen

5.1 Creating Onscreen help to assist the users of a

computer program

The Onscreen help is user assistance in a form of documentation that directs and navigates a user of a computer through step by step instructions to follow

when he/she does not know what to do next or encounters problems with an

application/program. It is also called Guidelines.

5.2 Introduction

Most computer programs use symbols or icons such as F1,? (Question mark) or

an icon named Help. A Screen pops up to actually ask questions on what the user precisely needs ( e.g. wizards).

Links for help are usually placed where users can find them easily such as in

navigation bar, side bar, top or bottom of screens.

Onscreen help makes a computer program easier to use because of the help provided for the user in the form of easily readable onscreen assistance with

program navigation. It therefore increases the program’s user-friendliness.

Onscreen help has mainly been used for software products (applications/programs), but it is increasingly becoming used for complex

professional products too, e.g. control equipment including a system PC.

Currently, there are seven different types of onscreen help/manuals/tutorials: The classical help function

Wizards

"Helpers"

Onscreen book type help (e.g. Acrobat) Onscreen videos

HTML-help Interactive tutorials

Selecting a combination depends, consequently, on a large number of factors,

e.g. Which kind of product are we to document?

Which users are to be addressed? Economy ( which country is it going to be used in)

Let us look at their advantages and disadvantages - in general and one-by-one.

5.3 General advantages and disadvantages of on-screen manuals

5.3.1 Advantages

Can contain internal and external links (all modern versions).

Can contain large amounts of information without having a "bulky look".

Relatively cheap or completely cost-free distribution. Fast and easy to update from the Internet.

5.3.2 Disadvantages

Difficult to display large screen-shots without reducing the image quality. The problem is that the original onscreen fonts and thin lines are

optimised for the full screen and cannot be reduced without becoming almost unreadable.

In most cases, available for pirate-users, too. The user must have access to a computer with a suitable reader

programme.

5.3.3 Some information needed to be presented to the user

outside the on-screen manual:

About 15% of all users want to read the manual from A to Z at least

once before they even try starting the installation. They need at least a "How to get started" chapter/booklet in order to reassure themselves

that they are not going to do anything wrong during installation.

Onscreen guidance during the installation is not enough. How to start the installation programme. If it is advisable to terminate

all other programs before starting the installation - including any virus checker - before starting the installation.

What to do if, for some reasons, you can NOT access the onscreen help. This information should include the local hot-line telephone number.

5.4 The classical "help" function

The classical "Help" function has developed over at least the last 20 years from

primitive text files to today's much more sophisticated functions including links, images, context oriented entries, sounds, videos, etc.

5.4.1 Advantages

It gives possibilities for explaining professional terms, abbreviations, etc. to beginners without disturbing any professional's reading habits.

Not page oriented: a "page" can have any size from one line to

thousands of lines with as many graphics as you want.

5.4.2 Disadvantages

Difficult/impossible to use the same content for a paper-based manual

and the onscreen help. Many people have problems getting on top of the screen windows at the

same time as they are performing the processes described. They, consequently, almost automatically print the pages needed.

5.5 Wizards

Wizards are not really on-screen help, it is rather a semi-automatic procedure,

where the user has to come to some decisions in some of the steps. Make sure that the user knows the background for answering the questions.

Very often, they do not. If not, offer some help. Wizards are most often used in addition to some other sort of help, e.g. "classical" help.

5.5.1 Advantages

Very useful method to guide the user through a complex procedure.

Very suited for one-time procedures like installation.

5.5.2 Disadvantages

The user never learns the "real" procedure - if it exists at all.

5.6 "Helpers"

Helpers are the "intelligent" help functions used e.g. in MS Word 97, where you

e.g. can type in a question and get assistance. Helpers are most often used in addition to some other sort of help, e.g. "classical" help.

5.6.1 Advantages

It does not look scary.

5.6.2 Disadvantages

Still not intelligent enough. Example: if the user does not find the "correct" term, no meaningful help will appear. Try e.g. in MS Word 97 to

ask for information about "secret" text instead of "hidden" text! If unsuccessful a couple of times, many users give up

Many users - especially academics - find it "childish" and consequently avoid using it.

5.7 The on-screen book type of help

The Adobe Acrobat format seems to have won the race becoming the de facto

standard.

5.7.1 Advantages

You can use the files for the printed version directly and even include

internal and external links.

List of contents and index can automatically become links. Easy to print out with a 100% controlled layout.

Platform independent (Windows, Mac, UNIX).

5.7.2 Disadvantages

Page oriented.

Dependent of the font used: may be difficult to read on a low-resolution (800x600 or less) screen.

Many people still do not have an Acrobat reader, or still only have the Acrobat 2.0 reader. Solution: always include the installation programme

for the reader with the help/manual file.

5.8 Creating onscreen help

5.8.1 These are the guidelines for on-screen help design:

(i) Anticipate problems which the users may encounter and prepare solutions.

(ii) Provide a convenient access mechanism to the help (easy access) (iii) Make sure that the users can easily and quickly understand the help

content. (iv) Help information should be well organised, logical and easy to grasp by

the users skimming through. (v) Present help information in a format that is easily readable on screen.

(vi) Refer users to additional methods of getting help when they require

assistance beyond what is provided in the help. (vii) Maintain the help content by updating it as often as possible and revising

the content to eliminate existing errors.

(i) The Onscreen help directs and navigates users of a computer

through step by step instructions to follow when he/she does not know what to do next or encounters problems. Guidelines.

(ii) Onscreen help makes a computer program easier to use because of the help provided for the user in the form of easily readable

onscreen assistance. (iii) It includes program navigation and, therefore, increases the

program’s user- friendliness. (iv) Onscreen help also refers users to additional methods of getting

help when they require assistance beyond what is provided in the

help. (v) The computer program or software will attain longevity. The faster

and easier a user can use this software, the more reliable it becomes and users will often use such program/product.

(vi) Sales: there will be improved sales results from the availability of easy-to-use product/software information.

Examples of onscreen help that can be found in computer programs (either

online or offline mode) are shown below:

Figure 4

Figure 5

Figure 6

Figure 7

Figure 8

NOTE The more directly the user can reach the desired item/information, the more successful the design is.

EXERCISES

ASSESSMENT TOOLBOX

Individual Exercises

Unit 6 – Documentation for the support and

maintenance of a computer program

This unit covers the following topics:

Documentation Different kinds of Documentation

At the end of this unit, students will be able to:

Understand and document programs in different ways

6.1 Creating documentation for the support and maintenance of a

computer program

6.1.1 Software/Program documentation

Comprehensive information on the capabilities, design details, features and limitations of a system or application software is included in software

documentation. It may also include software licensing requirements. It comes usually as a printed document or as another piece of software on a disk or CD.

It is also called software manual.

Documentation is said to be prepared, when detailed information about a

newly created program is given. Information such as the aim of the program (Topic/Title), who created the program (Author), when it is created (Date

written) and program functions, etc. is included.

The Program documentation gives a comprehensive procedural description of a program. It shows how software is written. Program documentation has the

capability to sustain any later maintenance or development of the program. The program documentation describes what exactly a program does by stating

the requirements of the input data and the effect of performing a program.

If one wants to know what a program is meant to do and how it has to be

executed, one should refer to the program documentation. The most common examples would be the instruction manuals for a software product, which is

given to the end-user. The instruction manual for a programming language like Pascal or for understanding a word processor can come under the category

of program documentation. The description languages used are informal and are intended to make it easy for the end-user to understand.

There is also another kind of program documentation that is written for the

sake of programmers who write the actual software and may have to modify it or use it as a part of another program which they write in the future. While the

end-user documentation has a user-friendly language about the software, the program documentation describes things in a language which can befit the

programmer’s level of skills.

Internal documentation of programs is very important, not just to the student

but also to the next programmer who will be modifying the program. Outside of academia, most programming consists of fixing bugs or adding features to

existing code. The comments students put in their source code files should be written to help

other programmers navigate through this code easily in order to find bugs or to determine where to add new features. Therefore, it is important to pay

attention to how the code is laid out on the screen (indentation matching) and to use meaningful variable names, as well as to write comments that are

concise but clear. Programmer documentation should be concise so the reader does not have to

spend too much time to find what he/ she is looking for. Even though the code will actually be read only by the student and the

instructor, they must write the comments as if they would be read only by

another programmer who needs to modify it. Writing documentation for the students’ program is one of the best ways they

can help their users. Users do not want to have to spend lots of unnecessary time trying to figure out how to use such program and experts consider a

program without documentation to be “distasteful”.

6.1.2 How to document a computer program

When naming their documentation, students must try not to use a generic

name like readme.txt. This is the current standard, but it does not work very well when a person has several programs stored in the same folder at the

same time. Instead, they should name their documentation after the name of

their program. For example, if their program's name is permutation, their documentation should be named permutation.txt. This makes it much easier to

maintain order.

There are different kinds of documentation, but to document a computer program for the purpose of support and maintenance, the following steps

should be followed:

1. User documentation: Users of a system are not all the same. The producer of documentation must structure it to cater for different user tasks and

different levels of expertise and experience. Description of the students’ classes and how to set up and run their project including screen shots are

also part of user documentation. Their screen layout should be pleasing to the eye.

2. Program design documentation: It involves giving their program a name,

state the goal and features of the program. 3. Source code documentation: Students must include comments in their

code and a prologue at the top of their program i.e. name of the file, author, date created, operating system and description of the program.

4. Project documentation: it makes maintenance of the code easy if students

make sure that every line of their code clearly explains what is intended to by structures and blocks in the code (i.e. comments). They should also

supply information on how to use and run their project and the expected output that will be displayed.

5. Project documentation makes it easier for people who have to maintain the code to know what exactly is being coded. It, therefore, enhances easy

maintenance for the support of the students’ program.

Documentation is also classified into two major categories:

a. Internal documentation

The variable declaration comments are one part of good internal documentation.

Internal documentation consists of the set of comments that are

included within the code to help clarify algorithms. Some take internal documentation to mean that they should

comment on each line of code. This is a good idea.

These are the list of items that should be included in your internal documentation:

1. "Block comments" (comments that are several lines long) should be placed at the head of every subprogram. These will include the

subprogram name; the purpose of the subprogram; and a list of all parameters, including direction of information transfer (into this

routine, out from the routine back to the calling routine, or both), Meaningful variable names. Simple loop variables may have single

letter variable names, but all others should be meaningful. Never use nonstandard abbreviations.

2. Each variable and constant must have a brief comment next to its

declaration that explains its purpose. This applies to all variables and also to fields of structure declarations.

3. Complex sections of code and any other parts of the program that need some explanation should have comments just ahead of them or

embedded in them.

External documentation External documentation does not deal with details of the code.

Instead, it serves as a general description of the project, including such information as what the code does, who wrote it and when,

which common algorithms it uses, upon which other programs or

libraries it is dependent, which systems it was designed to work with,

what form and source of input it requires, the format of the output it produces, etc.

Often, the external documentation will include structure charts of the outline of the program that were produced when the program was

being designed. All of this information is necessary to help other

programmers understand the program. One seemingly innocent change in a program can have unpredictable

consequences on other parts of the system. Good documentation can help prevent such problems.

In most programming classes, it is impractical for instructors to require large amounts of external documentation for programs that are only a few

hundred lines long. Instead, it is common for instructors to require that a small amount of external documentation be included at the top of the

program in the form of a large block comment. This condensed version should include at least the following pieces of information:

1. The student’s name, the course name, assignment name/number, instructor's name, and due date.

2. Description of the problem the program was written to solve. 3. Approach used to solve the problem. This should always include a

brief description of the major algorithms used or their names if they

are common algorithms. 4. The program's operational requirements: Which language system the

student used, special compilation information, where the input can be located on disk, etc.

5. Required features of the assignment that the student was unable to include.

6. Known bugs should be reported here as well. If a particular feature does not work correctly, it is in the student’s best interest to be

honest and complete about his/her program's shortcomings.

On-line documentation It is now normal to provide some on-line documentation with delivered

software systems. This can range from simple ‘read me’ files that provide very limited information about the software through interactive hypertext-based

help systems to a complete on-line suite of system documentation.

Most commonly, however, hypertext-based help systems are provided. These

may be based on a specialised hypertext system or may be HTML-based and rely on web browsers for access.

The main advantage with on-line documentation is, of course, its accessibility.

It is not necessary for users to find manuals, there is no possibility of picking up out-of-date documentation and built-in search facilities can be used to

locate information

In general, some of the types of documentation we have are:

(i) Project documentation (ii) Source code documentation

(iii) User documentation

(iv) Program design documentation (v) Internal documentation

(vi) External documentation (vii) Technical documentation

(viii) Online documentation

Example of documentation students must provide on computer programs:

Source file name Author's name: (person who wrote the program originally)

Last Modified by: (person who modified program last) Date last Modified:

Program description Main function's variable descriptions

EXERCISES

ASSESSMENT TOOLBOX

Learning Activity No. 5

Unit 7 – Examination Information and

Review

This unit will prepare the students for their initial examination.

The aim of this section is to review all the information that has been covered and to prepare the students for the initial examination.

At the end of this unit, students will be able to:

Understand how the semester test will work.

7.1 Initial examination information

The initial examination will cover all the work that has been covered in this course, in other words everything from Units 1–3. It will be a two-hour (120

minutes) examination consisting of:

Section A is compulsory and all questions must be answered, Section A will consist of 5 questions:

True or False questions for 5 marks Multiple choice questions for 5 marks

Comprehension type questions for 15 marks Application type questions for 15 marks

Application type questions for 20 marks

Section B will have questions from the assignments. Students can choose

either to answer Question 6 or 7.This section will be a total 20 marks Section C will be long paragraph type or essay questions totalling 20 marks.

There will be a choice between 8 or 9 to answer.

Please note that the examination will be 60%: Knowledge based

Application

And the other 40%: Evaluation

Analysis Synthesis

The examination will require insight and the application of the tools, techniques and theories that were discussed in this course.

Students should prepare for this assessment by reviewing all the course

content, class activities, etc. as well as the assignments that were handed in.

Glossary

Term Description

Array Structure that holds many variables of the same data type and are referenced with the same name.

Boolean It accepts a Boolean as a value.

Control structure The flow of program is directed to other part of the

program based on a condition or the result of a decision made.

Documentation Giving information about all the parts of a program.

Error detection The ability to detect errors that may occur during the writing, compiling and running of programs.

Functions It always returns value but may or may not accept parameters.

Global variable Variable declared to be used throughout an entire

program.

High-level

programming

English–like program that has to convert to machine

language before it can be executed.

Integer Basic data type that stores whole numbers as values.

Low-level

programming

Uses binary numbers (0’s and 1’s) to communicate

directly with the computer.

Memory registers Register of a computer’s control unit that contains the data to be stored in the computer storage such RAM

and ROM.

NAND False only if both inputs are true.

NOT It is an inverter which changes true input to false and

false to true.

NOR Result is false if either input is true.

OR Result is true if either input is true.

Parameters They are the arguments that are passed inside a function.

Procedures It may accept or not accept parameters but do not

return values.

Program flowchart Used to show the steps in the computer programs and

movement of each steps in the process.

Run-time errors Also called unchecked exceptions and occur while the

program is executing.

String Basic data type that accepts words as a value.

Structures It decides where the flow of control will be directed in

the program depending on the outcome of the decision made.

Static variable Variable declared inside the main program and re-

declared inside a procedure or function.

Syntax error Wrong spelling of keywords in the code.

System flowchart Shows the structure and the fitness of computer

programs in an information system.

Variable Used to store data used by the program, it is a name

formed with rules that can represent a number, character or word.

XNOR Result is false if and only if one of the inputs is true.

XOR Result is true if and only if one of the inputs is true.

Bibliography

Textbooks

Tony Gaddis, Haywood Community College, Starting Out with Programming Logic and Design, 3/E ISBN-10: 0132805456, ISBN-13:

9780132805452 Publisher by Addison-Wesley Hoare, C.A.R. (1969). An axiomatic basis of computer programming,

Communications of ACM 12, 10. Brinch- Hansen, P. (1975). The programming language Concurrent Pascal.

IEEE Transactions on Software Engineering SE-1, 2 (June). Williams, B.K. & S.C. Sawyer. (2007). The computer

Revolution/Programming/Designing the program. J. Glenn Brookshear (2011) , An Overview:International Edition, Pearson

Education, 9780273751397 0-27375-139-52

Maureen Sprankle, Jim Hubbard (2011). Problem Solving & Programming Concepts: International Edition, 9/E , ISBN-10: 0273752219 ISBN-13:

9780273752219 Davis, S R. (2009) C++ for Dummies (Wiley) ISBN-10: 0470317264

McBride, P K. (1997) Turbo Pascal Programming Made Simple ISBN 0750632429

McGrath, M. (2009) C Programming in Easy Steps ISBN 184078363X Parkin, A and Yorke, R. (1995) Cobol for Students (Butterworth

Heinemann) ISBN 0340645520

Websites

http://library.thinkquest.org/27297/ www.cplusplus.com/doc/tutorial/

ww.cprogramming.com/ www.csis.ul.ie/cobol/

Bedfordview Campus 1st Floor, 14 Skeen Boulevard

Bedfordview, 2008 P.O. Box 1389, Bedfordview, 2008 Tel: +27 (0)11 450 1963/4, Fax: +27 (0)86 686 4950 Email: bedfordview@cti.ac.za

Bloemfontein Campus Tourist Centre, 60 Park Avenue,

Willows, Bloemfontein, 9301 P.O. Box 1015, Bloemfontein, 9300 Tel: +27 (0)51 430 2701, Fax: +27 (0)51 430 2708 Email: bloemfontein@cti.ac.za

Cape Town Campus The Brookside Building, 11 Imam Haron Street

(old Lansdowne Road), Claremont, 7708 P.O.Box 2325, Clareinch, 7740 Tel: +27 (0)21 674 6567, Fax: +27 (0)21 674 6599

Email: capetown@cti.ac.za

Durban Campus 59 Adelaide Tambo Drive (old Kensington Drive)

Durban North, 4067 P.O. Box 20251, Durban North, 4016 Tel: +27 (0)31 564 0570/5, Fax: +27 (0)31 564 8978

Email: durban@cti.ac.za

Durbanville Campus Kaapzicht, 9 Rogers Street, Tyger Valley, 7530

P.O. Box 284, Private Bag X7 Tyger Valley, 7536 Tel: +27 (0)21 914 8000, Fax: +27 (0)21 914 8004 Email: durbanville@cti.ac.za

East London Campus 12 Stewart Drive, Berea, East London, 5241

PostNet Suite 373 Private Bag X9063, East London, 5200 Tel: +27 (0)43 721 2564, Fax: +27 (0)43 721 2597 Email: eastlondon@cti.ac.za

Nelspruit Campus

50 Murray Street Nelspruit, 1200 P.O. Box 9497, Sonpark, Nelspruit, 1206 Tel: +27 (0)13 755 3918, Fax: +27 (0)13 755 3918 Email: nelspruit@cti.ac.za

Port Elizabeth Campus

Building 4, Ascot Office Park Cnr Ascot & Conyngham Roads, Greenacres, 6065 P.O. Box 40049, Walmer, 6065 Tel: +27 (0)41 374 7978, Fax: +27 (0)41 374 3190 Email: port_elizabeth@cti.ac.za

Potchefstroom Campus 16 Esselen Street Cnr Esselen Street & Steve Biko Avenue Die Bult, Potchefstroom, 2531

P.O. Box 19900, Noordbrug, 2522 Tel: +27 (0)18 297 7760, Fax: +27 (0)18 297 7783

Email: potchefstroom@cti.ac.za

Pretoria Campus Menlyn Corporate Park, Building A 175 Corobay Avenue (Cnr Garsfontein), Pretoria, 0181

PostNet Suite A147, Private Bag X18 Lynnwood Ridge, 0040

Tel: +27 (0)12 348 3060, Fax: +27 (0)12 348 3063 Email: pretoria@cti.ac.za

Randburg Campus 6 Hunter Avenue, Cnr Bram Fischer Drive Ferndale, Randburg, 2194 P.O. Box 920, Randburg, 2125 Tel: +27 (0)11 789 3178, Fax: +27 (0)11 789 4606 Email: randburg@cti.ac.za

Vanderbijlpark Campus Building 2, Cnr Rutherford & Frikkie Meyer Blvds Vanderbijlpark, 1911 P.O. Box 6371, Vanderbijlpark, 1900 Tel: +27 (0)16 931 1180, Fax: +27 (0)16 933 1055 Email: vanderbijlpark@cti.ac.za

Group Head Office Fourways Manor Office Park, Building 1 Cnr Roos & Macbeth Streets, Fourways, 2191 P.O. Box 1398, Randburg, 2125 Tel: +27 (0)11 467 8422, Fax: +27 (0)11 467 6528 Website: www.cti.ac.za