Fortran 90 Program Documentation Requirements

Part 1 - External

Full size, professional programs require at least three documents. These are the Program Design Document, the User's Manual and the Technical Reference Manual. In this course, you may combine these documents into a single one, since your programs will be relatively short and simple. Your documentation should contain the following sections:

Cover Page -

Lists the course and assignment numbers, your name and my name.

Introduction -

Describes what the program does. Restates the problem.

Operating Instructions -

Explains how to run the program. This section serves as the User's Manual.

Input/Output Description -

Describes the input required by the program (if any) and the output it produces. Include the format of the data files and the units of all values having units.

Description of Algorithm -

This should be a complete description of the algorithm. This description should include prose plus pseudocode or a flowchart or both. This section serves as the Design and Technical Reference documents.

Sample Solutions and Test Results -

These are solutions to the problem using some method other than the computer program. They are often done by hand, but could include experimental or other results. Sometimes they are solutions for some special cases of the problem that are particularly easy (or at least possible) to solve by hand. These results should be explicitly compared to those from the program to demonstrate that the program works. The number of specific cases done should be sufficient to prove beyond a reasonable doubt that the program works.

Program Listing -

The complete list (.l) file produced by the compiler. Remember to include plenty of comments in your program.

Data Listing (if any)-

Input and output data files as appropriate. Output file may be screen output captured on your PC.

Your documentation should be neatly prepared and be in a binder with a clear cover. Computer printouts should be inserted into the binder so that they can be easily examined. Your folders will be returned after grading.

Part 2 - Internal

The following information must appear in your programs.

a) Program Header - The program header introduces your program. It should be formatted as follows:

! Program       (Module or Subprogram) Name:  xxxxx
! Version:      x.y
! Last Revised: (date)
! Filename:     (of this source code file)
!
! Student (or Programmer):        (Your name goes here)
! Course and Assignment Numbers:  CS-185 Program z
!
! (A brief description of what this program does and how it does it.
!  Include information about data file names and formats, program
!  limitations, etc.)
!
! (revision history if any)
!
! Variables:	(A complete list of the variables used in the program and
!                their meanings.  Include types and units (feet, kg, W, dollars,
!                etc.) of all variables having units.  For example,)
!
! real  Engine       - Size of engine in Cu.In.'s
! real  Max_Speed    - Maximum speed in RPM.

b) Other Comments - Your program must contain enough comments to make its operation easy to understand. Every major section should begin with a block of comment lines explaining what the section does. You can generally identify major parts of your program by looking at the early versions or the pseudo code you wrote while designing it. Comments may also be needed on the same line as particularly important statements. For example,

!
! Get user input
!
      ...
      READ(*,*) Make, Model, Year	! Get information about the car
      ...
!

c) Other Documentation - A logical program design, consistent indentation and mnemonic variable, subroutine and function names go a long way toward creating a well documented a program.