Programming Policies for CSCI Classes
 
Please keep in mind that your goal is to write programs (systems) which are:
bullet CORRECT
bullet RELIABLE
bullet MAINTAINABLE
bullet READABLE
bullet and EFFICIENT

The following guidelines are presented as suggestions to help you develop programs and solutions to achieve these goals.  You are expected to follow these documentation guidelines for all CSCI software courses at UHCL.   

1. Documentation for the main module/program should include:
   
bullet PROGRAMMER: your name
bullet  COURSE:   CSCI XXXX.X   (include section # if applicable)
bullet  DATE:   September 19, 1998
bullet ASSIGNMENT:  Number 1
bullet ENVIRONMENT: This program runs where?  DOS, UNIX...?
bullet FILES INCLUDED: List all filenames starting with main, and include header files,  input/output, executable, etc. when applicable
bullet PURPOSE:  A problem statement of what is done
INPUT:  Data used as input described here
bullet PRECONDITIONS:    Assumptions for correct execution of this code
bullet  OUTPUT:  Output data is indicated
bullet POSTCONDITIONS: Assertions that describe the results of actions taken by cod
bullet ALGORITHM: How the program works.  This should be structured using short, descriptive phrases that are indented appropriately.  At the beginning of the program, you will have an overall algorithm to describe the flow of the entire program.  For each nontrivial module an algorithm will describe how that module works or will make a very specific reference to an existing algorithm (eg.QuickSort, BinarySearch), if a well-known algorithm is used.
bullet ERRORS:  What happens in case of  unexpected input (optional)
bullet EXAMPLE: A sample execution in terms of input and corresponding output  (if appropriate)
bullet HISTORY: Useful if a sequence of assignments is based  on the same project  (optional)
 
2. Items g through l will also appear as a preface to each module or subprogram unit.  The Input, Output, Preconditions and Postconditions fields may be replace with Parameters and Actions fields when they are more meaningful.
   
3. Variable names should be appropriate and meaningful.  For clarification, variables may also be defined by line comments.  Extreme abbreviation of identifier names should be avoided.
   
4. Reserved words may be indicated by using different fonts, all capitals or bold, in order to visually separate them from the rest of the code.  See the example in #5.
5. Indentation -- should be 2 or 3 spaces and should be uniform throughout the program.  Suggested format:
IF condition THEN
   action;
ELSE
   other_action;
END IF; (or ENDIF, or nothing, depending on the language)
   
6. Multiple conditions in an IF clause should be grouped together, placed on appropriate lines and aligned to enhance clarity:

IF (condition1 AND condition2 AND condition3 ) OR
    (alternate_condition1 and alternate_condition2) THEN
       action;
END IF;
   
7. BEGIN, END, {, }, EXCEPTION, IF, THEN, WHILE, END IF, etc. should be properly aligned and indented within each unit.
   
8. Statements in a module, including declarations, should be indented or spaced from the heading in such a way as to let the heading stand out from the rest of the code.
   
9. The size of a module should normally not exceed one or two computer pages in length, and should generally not exceed 100 lines.
   
10. Highlighting:  the beginning of the body of each module, and the beginning of the outermost block of the main program should be highlighted in some way (asterisks, box, etc.)

    ------------------------------------------------------------------------------------
    -- PURPOSE:  to read a sequence of numbers and report:
    --            - the count of positive integers
    --            - the count of negative integers
    --            - the sum of the positive integers
    --
    -- INPUT:  array of integers called INPUT_INTEGERS
    --
    --PRECONDITIONS: the array contains only integers; no real numbers,
    --         or characters of any kind
    --
    -- ...
    -- ...       see the Example at the link at the bottom of this page
    ----------------------------------------------------------------------------------------

A comment requiring special attention -- a warning, temporary patch, etc. should be highlighted.

   
11.  Comments:  Blank lines and comments should be used liberally.  Comments can precede any relatively long set of related   statements.

      An ELSE located more than a few statements away from it's IF should contain a comment
      indicating what condition causes execution of statements in its scope:

IF Pay > Normal THEN
     PROCESS (PAY);
ELSE          /* since Pay <= Normal*/
    ALTERNATE_PROCESS (PAY);
END IF;
   
12. Output Documentation:

Comments on the output itself should indicate what the output is, how to read or interpret the output, or how to generate the output file.  Column and row data items should be identified.  Above all, output should be easy to read and understand.

   
13. Misc:

Use a table of contents (a list of the modules/packages in the listing in order of appearance) if it is appropriate.

   
  For an example of a program which follows these guidelines, click here.