B211 Guidelines for Programming

Guidelines for Programming

Operation

Does the program work according to the requirements? (Very important)

How easy and intuitive is the interface(s) to use?

Is the program prone to crashing?

Does the program have extra features (beyond the requirements but not violating the requirements)? If there are extra features, please state them clearly in a separate section in your documentation.

Source Code

Program readability - easy to determine what the code does. Including:

Concise code - this means not using unnecessary code. It does not mean having as few lines of code as possible. Lines of code in itself doesn't usually mean much.

Code layout - proper indentation, control statements blocks aligned, no lines wrapped around the screen (we usually work on a screen size of 80 columns, and tab-stops of 8), blanks lines to separate subroutines and blocks, etc.

Statements as simple as possible.

Data structures and subroutines with appropriate names.

Comments in the source code (for yourself and for other programmers in the future), including:

Every script file must have a comment section at the beginning indicating what it does.

Every subroutine must have comments at the beginning indicating what it does, what input it takes, what return values it gives - just consider that another programmer who wants to use your subroutine, should be able to do so just by reading your comments and not having to read the subroutine's code at all.

Major data structures must have comments describing what they represent - unless it is obvious from their names.

Future modifiability - easy to make changes in the future. Including:

Program broken into appropriate independent sections (using subroutines if appropriate) - this makes it easy to modify, since any modifications only require changes to small sections of code. It also makes the program easier to understand.

Efficiency - in time (executes quickly) and space (low file and memory requirements). Including:

Good data structures

Good use of control structures

Good use of subroutines

Good use of existing functions and data structures in the language

A lot of the above criteria conflict with each other. You job as a programmer is to find a good balance.

Documentation

All submissions should include the following documentations:

Instructions on how to install and start your application.

Online help for users, for parts of which may not be obvious for users exactly what to do.

Architectural design description - descriptions of the design of your program for future programmers (including yourself) who may change and extend your source code.

Description of tests done on the final program, with sample inputs and sample outputs - testing should include at least the following data:

different normal data with results.

faulty data which returns error messages.

faulty data which crashes the program (if any) - to show that you know about it.

A statement of what works and what doesn't, and which requirements you have not satisfied. Test your programs extensively - you will be severly penalised if you claim that a requirement is satisfied but the assessor finds that it doesn't.

The above criteria applies to most scripting and programming activities. Keep them in mind for the future. A major variation is the weight of the different components - in most real-world projects, the importance of documentation is overwhelming, and will contain a lot more components than what I have listed above.

H.L. Hiew
Unit Coordinator