6C. Documenting a Program

Documenting a Program

---

Production software has extensive documentation, often in the form of a book. Obviously, you don't have time for that in this course. But the standards for this course do require some documentation to be written in the program.

Write a comment near the beginning of every program telling what the program does, so that someone who looks at the program will immediately know the program's purpose and how to use the program without the need to reverse-engineer the program. The standards require such a comment.

Make the comment include the following information, not necessarily in the order given. Just make sure that all of the information that a reader needs is present.

1. An indication of what information the program reads, where the input comes from, and what the input format is.

2. An indication of what the program writes, where it writes information. Usually an example suffices to show the output format.

3. A sample run, with input and output.

Where convenient, give things names so that you can refer to them by their names rather than by phrases such as "the input number."

If you want to write a list, show it as a numbered list; don't pack the list into a paragraph.

You are allowed to copy material from the assignment document into the initial comment. That will not be considered plagiarism.

Here is a sample.

  // This program reads a single positive integer, n, and writes 
  // information about the hailstone sequence that starts with n.
  // It shows the sequence, the sequence length and the largest
  // number in the sequence.
  //
  // Example:
  // Input:  
  //   5
  // Output:
  //   The hailstone sequence starting with 5 is
  //   5 16 8 4 2 1.
  //
  //   The sequence length is 6.
  //
  //   The largest number in the sequence is 16.

Notice that the comment gives a name, n, to the input, and refers to the input as n. It does not use awkward phrases such as "the number that was read from the user."

You can use the above comment in a program that you submit. It will not be considered plagiarism.

A complete program

---

Here is a complete C++ program. It uses function atan(x), which is tan⁻¹(x), also called arctan(x), and which is available if you include <cmath>.

// Author:    Karl Abrahamson
// File:      example.cpp
// Tab stops: none

// This program reads two points (x1, y1) and (x2, y2)
// from the standard input, with the requirement that
// x1 != x2.  The input format is
//   x1 y1
//   x2 y2
// It writes the angle between horizontal and the
// line that goes through points (x1, y1) and (x2, y2), in radians, on the
// standard output.
//
// For example, on input
//   1.0 1.0
//   2.0 2.0
// It shows:
//
// The two points are:
// A = (     1.000,      1.000)
// B = (     2.000,      2.000)
//
// The angle between horizontal and the line from A to B is
//     0.785 radians.

#include <cstdio>
#include <cmath>
using namespace std;

//================================================
//                    getAngle
//================================================
// getAngle(x1,y1,x2,y2) returns the angle between
// a horizontal line and the line that goes through
// (x1,y1) and (x2,y2).
//================================================

double getAngle(double x1, double y1, double x2, double y2)
{
  double rise = y2 - y1;
  double run  = x2 - x1;
  return atan(rise/run);
}

//================================================
//                    EchoInput
//================================================
// EchoInput(x1,y1,x2,y2) shows the input points
// (x1,y1) and (x2,y2) on the standard output.
//================================================

void EchoInput(double x1, double y1, double x2, double y2)
{
  printf("The two points are:\n");
  printf("A = (%10.3lf, %10.3lf)\n", x1, y1);
  printf("B = (%10.3lf, %10.3lf)\n\n", x2, y2);
}

//================================================
//                    ShowOutput
//================================================
// ShowOutput(angle) shows the result angle 'angle'
// on the standard output.
//================================================

void ShowOutput(double angle)
{
  printf("The angle between horizontal and the line from A to B is\n");
  printf("%10.3lf radians.\n", angle);
}

//================================================
//                      main
//================================================

int main()
{
  double x1, y1, x2, y2;

  printf("What are the points?\n");
  int numRead = scanf("%lf%lf%lf%lf", &x1, &y1, &x2, &y2);
  if(numRead != 4)
  {
    printf("I could not read the points\n");
    return 1;
  }
  else
  {
    EchoInput(x1, y1, x2, y2);
    double angle = getAngle(x1, y1, x2, y2);
    ShowOutput(angle);
    return 0;
  }
}