Program Guidelines

Program Guidelines

These program guidelines were originally written by Professor Zimmer, but I have modified them extensively.

All program files should begin with comment lines that identify the following information:

Your name
Class and section
Date
Assignment number
Narrative about the program or file
Special notes ( additional features or features not implemented)

/*
   Program 1:  Find the Missing Link
   Programmer: Dan Bennett
   Class:  CSCI 000,  Spring 2001 
   Short Description:  This program simulates the evolution of 
        species to find the missing link between ape and man.

   Narrative:
        This program ...

   Special Notes:
      *  If you run this program with the -G flag, the program will
	 simulate the presence of God, and thus no missing link will be
	 found, man is just created.
      *  This program ...
*/

All modules should begin with comment lines that identify the following information:

Narrative about the module
Interface information

/* 
   Module: Genesis
   Input: 
           days:    an integer specifying the number  of days
	   species: an integer specifying the number of different
	              species to generate
   Input/Output: 
           world:   a two dimensional array of species, empty on 
	              input, populated on output.
   Output:
           done:    boolean, true if the creation succeeded, false if
	              it fails for any reason.

   This module will simulate the creation according to the chapter of 
    Genesis.   It will ....
*/

Identifier names should be meaningful.

     Acceptable: worldArray, numberOfSpecies, currentYear
     Poor: a, b, wrdary, foo, bar, foobar

Identifier names should be consistently formatted:

     worldArray, numberOfSpecies for variables 
     Genesis, GrowTheTrees for  functions/procedures
     TOTAL_YEARS, MAXIMUM_TIME  for constants

Constants should normally be declared and named. Your program should contain no "magic" numbers.
```
     const int TOTAL_YEARS = 10000;
```
This is a tricky rule, if a number has a meaning, make a name for it. If it does not, don't bother. For example, there is no reason to name a constant for formatting output. The following is definitely useless and, to me, somewhat annoying.
```
     const int FIVE=5
```

Use comments within the code wisely.

DO NOT comment every line.

       // prompt the user for a
       cout << "Input the length of side A -> " ;
       // read in a
       cin >> sideA;
       // print the end of line 
       cout << endl;

Do comment major sections of the code.

      // get the value of the second side.
       cout << "Input the length of side B -> " ;
       cin >> sideB;
       cout << endl;

DO NOT repeat the code in the comment

      // let c be the square root of a*a + b*b 
      hypot = sqrt(sideA*sideA+sideB*sideB);

Do describe what the code is doing at a high level.

      // use the Pythagorean Theorem 
      hypot = sqrt(sideA*sideA+sideB*sideB);

This is also tricky. I would rather have self documenting code, with good identifier names, and fewer but descriptive high-level comments. Not everyone agrees with this, but this is my style.

Use blank lines to make the program easier to read.
Each statement should usually be on a separate line.
All interactive input statements should be preceded by a user friendly prompt.
You should tell the user what you want. Both in terms of value and of type. Unless instructed otherwise, you may assume that the users of your program know the types and will follow your instructions for input.
Proper indention of program structures must be used.
- Each new block should be indented.
- The body of control statements should be indented.
- I find four spaces about right
  - Fewer, it is hard to tell the indentation quickly
  - More, lines become too short in nested loops.
If your code is not properly indented, the first thing I will do when you ask me to debug it is make you do this. Often, this is sufficient to find a number of errors.
Only one entrance and one exit are permitted in the main program, modules, and control structures. If appropriate functions may have multiple return statements to improve readability, but NEVER to replace poor logic. No GOTO statements may be used in the program unless explicitly instructed to do so. Break statements may only be used in switch statements, and continue statements are not permitted.

I tend to violate this rule somewhat. I prefer this:
```
    if("cat" == critterType) {
       return (1);
    } else if ("dog" == critterType) {
       return(2);
    } ...
```
to this:
```
    int returnValue;

    returnValue = 0;

    if("cat" == critterType) {
       returnValue = 0;
    } else if ("dog" == critterType) {
       returnValue = 1; 
    } ...

    return returnValue;
```
The main program and modules should be a maximum of one page (screen) in length. Little or no detail code should exist in the main program.
Smaller more readable modules are preferred. Never have huge blocks of code repeated.

Duplication of code should be ~~avoided~~ eliminated. If something is done multiple times, write a routine to do it. The following code can be greatly simplified

   cout << "Enter your First Name =>";
   cin >> firstName;
   cout << endl;
   cout << "Enter your Last Name =>";
   cin >> lastName;
   cout << endl;
   cout << "Enter your Middle Name =>";
   cin >> middleName;
   cout << endl;
   cout << "Enter your Title =>";
   cin >> titleName;
   cout << endl;
   cout << "Enter your Nickname =>";
   cin >> nickName;
   cout << endl;

I would prefer the following:

/*
This function prompts the user for a string.  It will read the 
string into a single string variable, clean up the input stream
and return the value

Input:
   The name of the the string the user wants (part of the prompt)
Output:
   The string the user typed.  No type checking is performed
*/

string PromptForString(string prompt) {
   string tmp;
   cout << "Enter your " << promt << " => ";
   cin >> tmp;
   cout << endl;
   return tmp
}
...

// ask the user for a bunch of name related information
firstName = PromptForString("First Name");
lastName = PromptForString("Last Name");
middleName = PromptForString("Middle Name");
title = PromptForString("Title");
nickName = PromptForString("Nickname")

Functions should be cohesive.
1. Functions should accomplish a single task.
2. Functions should either contain low level or high level code. Only rarely a mix of both.
Program specifications will be provided for each program. The specifications may not include all the details about the program. As programmers it is your responsibility to fill in the gaps by asking questions. Do not assume anything! We will discuss program details in class. It is your responsibility to make note of these details and implement your program accordingly.
Programs will be graded on the following:
- Correctness
  - Does the program compile? (if not, no credit)
  - Does the program do what it is required to do?
  - Does the program violate any instructions in the assignment statement?
  - Does the program employ required techniques, algorithms, and other structures?
- Documentation
- Structure of program
- User friendliness
- Other