B336 Programming Guidelines

Guidelines for Programming

Here are some simple guidelines for things to look out for when programming:

Operation

Does the program work according to the requirements?

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

Is the program prone to crashing?

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 for source code actually conflict with each other. You job as a programmer is to find a good balance.

Documentation

Help, tutorials and references for users.

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.

Some notes about the criteria:

In my experience, in large-scale software, the program documentation (online, printed, and comments in code) is more important that than the programs themselves. This is because complex programs without proper documentation are very difficult for users to use, are limited in their future modifiability, and also limited in reusability by other programmers and programming teams. For this reason I always stress documentation when it comes to writing large programs.

But having said that, in this unit, I will ask you to produce very little documentation. The reason is that I want to maximize your time in learning to construct the source code. But keep in mind the importance of documentation anyway.

H.L. Hiew
Unit Coordinator