Documentation Standards

1. For each main program file
Each main program documentation the following should be included at the beginning of the main file.
• The author of the program
• The title of the project
• A description of the purpose of the project.
2. For each subprogram (function or procedure)
Each subprogram should contain the following just before the subprogram header:
• The name of the subprogram
• A functional description of the purpose of the subprogram
• What values are needed by the subprogram
• What values are produced by the subprogram
• The behavior of the subprogram
• A description of each parameter of the subprogram
• The required initial value of the parameter
• The value of the parameter after the execution of the subprogram.
3. For each program module (not containing a main program)
Each module should have documentation similar to the main program file.
• The author of the module
• The title of the module
• A description of the purpose of the project.
4. For inline documentation
Inline documentation should be included whenever it would aid in the reading of the program.  In particular,
• Declared variables should have a discription of their use when declared
• Major program structures should have an indication of their purpose.
5. White space
White space (blank lines) should be included within the source program to separate major portions of
the code.  This will allow the reader to better read your code.

Example

#include <iostream.h>
#include <time.h>
#include <stdlib.h>
#include <fstream.h>

// Subprogram name: Initialize
// Description:
//    This procedure will accept the output file name from the user as well
//    as accepting how many random numbers will be generated.
// Parameters:
//    filename: This string parameter has no defined starting value.  Its final
//       value will be the user selected output file name.
//    N: This integer parameter has no defined starting value.  Its final value
//       will be the user select number of random values to be generated.

void Initialize(char filename[], int &N)
{ // accept the output file name
  cout << "Enter your output filename: ";
  cin.getline(filename, 80, '\n');

  // accept the number of random values to be generated
  cout << "Enter the number of random values to generate: ";
  cin >> N;
}  // end Initialize
 

// Subprogram name: FillArray
// Description:
//    This procedure will fill an array with random numbers
// Parameters:
//    array: This integer array has no defined starting value.  Its final value\
//        will contain N random values, indexed from 0 to N-1
//    N: The starting value of this integer variable will be the number of random
//        numbers to be generated.  It will be unchanged by this procedure.

void FillArray(int array[], int N)
{int Count;         // used as a counter in a for loop
 srand( time(0));   // randomize the random number generator usint the system clock.

 for (Count=0; Count < N; Count++)  // generate N random numbers into an array.
    array[Count] = rand();
}  // end FillArray
 

// Subprogram name: WriteValues
// Description:
//    This procedure will write the generated random numbers onto the user
//    selected output file.
// Parameters:
//    filename: The starting value of this string variable will be the user select
//        name of the output file.  It will be unchanged by this procedure.
//    array: The starting value of this integer array will contain N integers
//        indexed from 0 to N-1.  It will be unchanged by this procedure.
//    N: The starting value of this integer variable will be the number of values
//        to be writen to the output file.  It will be unchanged by this procedure.

void WriteValues(char filename[], int array[], int N)
{fstream RandomFile;  // the output file variable
 RandomFile.open(filename, ios::out);  //Open the output file variable

 cout << filename << "    " << N << endl; // display file name and size of array

 // write all numbers to the output file
 for (int i = 0; i < N; i++)
  RandomFile << array[i] << endl;

 RandomFile.close();  // close the output file
}  //end WriteValues
 

// main program

void main()
{ char FileName[80];  // string to contain the filename
  int Count;          // the number of random values to be generated
  int RandomArray[10000];  // the array of random values

  Initialize(FileName, Count);  // obtain output file name and number of random values
  FillArray(RandomArray, Count);  // generate the random numbers
  WriteValues(FileName, RandomArray, Count);  // write the random numbers
}  // end main