Please keep in mind that your goal is to write programs (systems) which are:

     CORRECT
     RELIABLE
     MAINTAINABLE
     READABLE
     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 be placed before any code and should include:

     a. PROGRAMMER: your name

     b. COURSE:   e.g., CSCI 3321   (include section #)

     c. DATE:   e.g., March 23, 2022

     d. ASSIGNMENT:  e.g., Number 1

     e. ENVIRONMENT: Operating System and Version Number, e.g. DOS 6.0, Windows 2000, Solaris 8.

     f. FILES INCLUDED: List all filenames starting with main, and include header files,  input/output, executable, etc. when applicable

     g. PURPOSE:  A problem statement of what is done

     h. INPUT:  Data used as input described here

     i. PRECONDITIONS:    Assumptions for correct execution of this code

     j. OUTPUT:  Output data is indicated

     k. POSTCONDITIONS: Assertions that describe the results of actions taken by code

     l. 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.

     m.  ERRORS:  What happens in case of  unexpected input (optional)

     n.  EXAMPLE: A sample execution in terms of input and corresponding output  (if appropriate)

     o.  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
replaced with Parameters and Actions fields when they are more meaningful.

2.5.  Please place the function documentation immediately after the function definition.

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 lowercase, 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 3 or 4 spaces and should be uniform throughout the program.  Please do not use tabs! Suggested format:

     if condition then
         action;
     else
         otherAction;
     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
         (alternateCondition1 and alternateCondition2) 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 (how many screens does this translate to?) 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 InputIntegers
         --
         --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*/
         AlternateProcess (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.

Last updated:  May 14, 2020