1. 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 ...
   */
   

2. All functions should begin with comment lines that identify the following information:
   • Narrative about the function
   • Interface information

   /* 
      Function: 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 function will simulate the creation according to the chapter of 
       Genesis.   It will ....
   */
   

3. Identifier names should be meaningful.

        // Acceptable: 
        string  worldArray;
        int numberOfSpecies;
        long currentYear;
        // Poor or unacceptable:
        int a, b;
        string wrdary, foo, bar, foobar;
   

4. Identifier names should be consistently formatted:

        // variables
        string worldArray;
        int numberOfSpecies;
        // functions 
        void Genesis(...);
        int GrowTheTrees(...) ;
        // constants
        const long TOTAL_YEARS = 2000000;
        const long MAXIMUM_TIME  = 1000000000;
   

   In addition, I like to end types with a T, this indicates type.

         class SpeciesT {
            ...
         };
   
         typedef unsigned char  MonthT;
        

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

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

7. Use blank lines to make the program easier to read.

8. Each statement should usually be on a separate line.

9. 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.
   • However, if the instructions provide a standard for interaction, this must be followed.
10. 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.

    • // unacceptable
           int value;
           int max, 
      min;
           int count=0;
           cin >> value;
            max = value;
         min = value;
           while (cin) {
         if(max < value) {
          max = value;
      }
           if (min > value) {
          min = value;
          }
               count ++;
          cin >> value;
           }
      
      // *********************************************************************
      // acceptable
           int value;
      
           int max, 
               min;
      
           int count=0;
      
           cin >> value;
           max = value;
           min = value;
      
           while (cin) {
               if(max < value) {
                   max = value;
               }
               if (min > value) {
                   min = value;
               }
               count ++;
               cin >> value;
           }
          

    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.

11. Code blocks and bracket placement.
    • There are a number of styles for placing code blocks in c++ (see this article
    • I use K&R style.

    • // not a proper solution to fizzbuzz but I wanted single line nested if.
      int main() {
          int count;
          int i;
      
          cout <<  "Enter a positive integer :";
          cin >> count;
      
          for(i=1; i <= count; i++) {
             if (i%3 == 0) {
                cout << "Fizz";
             } else if (i%5 == 0) {
                cout << "Buzz";
             } else {
                cout << i;
             }
      
             cout << endl;
          }
      
          return 0;
      }
      

    • You may use the book's style (Allman) , but you should be consistent
    • You should use code blocks for any control structure, even if the body is only one line.

      // not a proper solution to fizzbuzz but I wanted single line nested if.
      // while this takes up less space, I feel it is more error prone
      //     you should not use this style in my classes.
      int main() {
          int count;
      
          cout <<  "Enter a positive integer :";
          cin >> count;
      
          for(i=1; i <= count; i++) {
             if (i%3 == 0) 
                cout << "Fizz";
             else if (i%5 == 0) 
                cout << "Buzz";
             else 
                cout << i;
             
      
             cout << endl;
          }
      
          return 0;
      }
          

12. 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 = 1;
        } else if ("dog" == critterType) {
           returnValue = 2; 
        } ...
    
        return returnValue;
    

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

14. 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 " << prompt << " => ";
       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")
    

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

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

17. Unless specified otherwise, you may not uses elemets from the standard template library or the standard container library. Part of the purpose of this class is to understand how to build these items. If you are unsure, please consult your instructor before using an item we have not discussed in class.

Programs will be graded on the following:

• Correctness
  • Does the program compile? (if not, no credit)
    • The code should compile, using any specified warning flags, without warnings.
  • Does the program do what it is required to do?
    • I am usually "offended" if the program does not run on the data given in the project description.
      • This tends to be a high point value deduction.
    • However, the data given in the project description is usually not sufficient.
    • Other cases should be employed to thoroughly test your program.
  • Does the program violate any instructions in the assignment statement?
  • Does the program employ required techniques, algorithms, and other structures?
• Documentation
• Is the code readable
• Does it follow a consistent style
• Is there appropriate use of :
  • Self documenting variable names, function names, constant names?
  • Constants? No magic numbers.
  • White space?
  • Indentation of blocks of code?
  • Comments
• Structure of program
  • Appropriate use of functions
    • NO REPEATED CODE.
    • Properly passed parameters.
    • Short, simple functions.
  • Reasonably efficient code.
  • Appropriate use of data structures.
  • Appropriate use of system libraries.
  • Appropriate level of data abstraction/information hiding.
• User friendliness
• Prompts for all input
• Labels for all output
• Neatness and legibility
• Other
• Compiles with the assigned flags.
• Complies with all instructions for submission.
• Does not use prohibited programming constructs/libraries.
• Is developed in the assigned file layout.
• Employs required tools.