CS 240A/B/C and CS 361 C++ Programming Standards

PURPOSE

PROPER ATTRIBUTION

g++ -g -Wall -Werror -O2 proj1.cc -o proj1

This produces an executable file called proj1 which you can run using the command:

./proj1

The -g flag tells the compiler to include information needed by the GDB debugger. When given the -Wall flag, the compiler will print out every warning that it can generate for your code. The -Werror flag causes the compiler to consider every warning to be an error. Properly formatted code does not produce warnings. For most purposes, you should compile with the -O2 flag. The compiler will produce more warnings this way. However, the -O2 flag can cause unpredictable behavior in GDB, so when stepping through code in the debugger, compile with -O0 instead.

The use of Makefiles to aid the compilation process is highly recommended in general, and required for CS361/561N. Makefiles contain a set of instructions to build your program. The file is read when you type 'make' at the command line. Makefiles can save time by checking dependencies and compiling only modified code.

Each class should usually be defined in a separate file. Template functions should be in a file with a suffix of .template or .temp. Template functions are encouraged since they allow greater code reuse.

Each set of functions and/or classes that implements a different algorithm or data structure should be in a separate set of files. This allows better organization of your code, and eases code reuse.

Template files should be included at the end of header (interface definition) files (.h).

Recall that abstract data types are defined by describing the interface to the data type in the .h file, the implementation in a .cc or .template file, and are used by including the .h file.

INTRODUCTORY DOCUMENTATION

1. The file name, your name, your email, and recitation section.
2. A brief description of the code in the file that describes the method(s) or algorithm(s) used to obtain the solution(s), the major data structures (if any) in the program, and other general comments including extra features.
3. The date the program was completed.

The format to be used is as follows:

//******************************************************************* 
//                                                                    
//  Program:     program name                                            
//                                                                     
//  Author:      your name
//  Email:       your email address
//                                                                    
//  Lab Section: section number and instructor's name
//                                                                    
//  Description: brief description of the program                    
//                                                                    
//  Date:        date of completion
//                                                                    
//*******************************************************************

The following is an example of an introductory comment block that follows the format above:

//******************************************************************* 
//                                                                    
//  Program:     Project 1 -- Video Calculator
//                                                                     
//  Author:      Elwood Scuggins
//  Email:       Clueless@ace.cs.ohiou.edu
//                                                                    
//  Lab Section: 10 (Chris Hayes)
//                                                                    
//  Description: This program inputs the total number of minutes, 
//               the number of minutes for commercials, and the 
//               number of minutes for episodes.  The program 
//               computes the total number of minutes for videos, 
//               the number of videos, and the number of seconds 
//               left over.
//                                                                    
//  Date:        January 26, 2001
//                                                                    
//*******************************************************************

DECLARATIONS

1. You should use mnemonic names for all identifiers. These are names that have meaning in the problem. The names should suggest the use of the identifier.

2. You should use built-in constants for any values for which they make sense. For example, use the built-in constant NULL to set pointers to null, rather than 0.

3. Constant values used in your program should be given in const declarations. Constant identifiers should always appear in all-capital letters. For example:
   

         const float BASE = 2.0;       // divisor to obtain base 2
         const char HYPHEN = '-';      // signals word continued on next line
         const int NAME_LENGTH = 20;   // names can be 20 characters
         

4. You should not have any "bare" constants in your program. If you need to use a value of say 20 somewhere in your code, define a constant with that value whose name means something, like MAX_NUMBER_NODES.

5. For anything other than constants, identifiers should be all-lower case letters (for example, student, temperature, weight, salary). Underscore characters should be used to delimit multiple words in an identifier. For example, ship_rates instead of shiprates, id_entry instead of identry, num_items instead of numitems, and min_score instead of minscore.

   It is permissible to capitalize the first letter of words in an identifier with class, structure, union, or type names. For example, you may wish to use Student, StudentName, or ListNode as names for your classes.

6. Each identifier declaration (including function declarations) must be accompanied by a comment that explains its use.

7. Avoid declaring globally-visible variables. Globally-visible constants, enumerated types, structures, classes, and file names are okay, but do not use global variables unless the project assignment specifically tells you to do so.

1. Each constant and variable declaration should be on a separate line that includes a comment that explains what each is. For example:
   

         float volts;                     // voltage in the circuit 
         int amps;                        // amperage in the circuit 
         char circuit_name[NAME_LENGTH];  // name of the circuit 
         

2. Each statement should be on a line by itself. For example, instead of
   

         left = next_left;    right = next_right;
         

   use

         left  = next_left;     // move to the left
         right = next_right;    // move to the right
         

3. Each class should have a comment block in the .h file describing the purpose of the class, operations it supports (generally these will be provided through its public member functions), and how it is typically intended to be used. The reasons for any friend classes in the class should also be explicitly stated, as well as any dependencies on other classes.

4. Each function, whether it is a member function or ordinary function, should be identified by a comment block describing its purpose, parameter(s), and the function(s) it calls. The format to be used is as follows:

         //******************************************************************
         //                                                                  
         //  Function:   find_space_cost
         //                                                                  
         //  Purpose:    calculates and returns the charge for shipping cargo  
         //              between two planets.                                  
         //                                                                  
         //  Parameters: distance - distance in miles between two planets
         //              weight   - weight in pounds of item being shipped
         //                                                                  
         //  Calls:      function cargo_rates
         //                                                                  
         //******************************************************************
         

   This detailed comment should be placed in the implementation file, as which functions are called, etc. is not of general interest to someone who merely wants to use your class/function. A short version of the above comment should be placed in the .h file.

5. Comments should be set apart from the code by at least two spaces, making it easy to see where the code ends and comment begins.

6. The main function should begin with
   

         int main ()
         

7. Use the endl construction (instead of \n) to indicate end-of-line, when not already in a string. For example, use
   

         cout << "Today's date is " << today << endl;
         

   instead of
   

         cout << "Today's date is " << today << "\n";
         

The body of a control structure, such as an if, a switch, a while, a do, or a for statement, should be indented. Always use curly braces even if there is only one statement:

if (expression) {
   statements
}
    

if (expression) {
   statements
} else {
   statements
}
    

switch (selector variable) {
   case case-1-value: case 1 statements;
        break;
   case case-2-value: case 2 statements;
        break;
   ...
   case case-n-value: case n statements;
        break;
   default: default statements;
        break;
}
    

while (expression) {
   statements
}


do {
   statements
} while (expression);


for (initialization; test; increment) {
   statements
}

if (expression)
  {
    statements
  }
    

if (expression) 
  {
    statements
  }
else 
  {
    statements
  }
    

switch (selector variable) 
  {
    case case-1-value: case 1 statements;
      break;
    case case-2-value: case 2 statements;
      break;
    ...
    case case-n-value: case n statements;
      break;
    default: default statements;
      break;
  }
    

while (expression) 
  {
    statements
  }


do
  {
    statements
  } while (expression);


for (initialization; test; increment)
  {
    statements
  }

PROGRAM DESIGN

1. Use stepwise refinement. The programming assignments given are ones that can be solved in a step-by-step manner. The method of solution used in your program should exhibit this kind of structure.

2. Modularize your program. When a problem solution readily splits into distinct tasks, your program should handle each task in a separate function and in a straightforward manner. Each set of functions for a particular task should be in a separate file.

3. Make your program efficient. Your algorithm should be direct and not unnecessarily complicated. Proper use of data structures will often simplify an algorithm. Document the efficiency of your routines in comments.

4. Use parameters appropriately. All variables used in a function should either be declared as parameters or be declared locally within the function.

5. A good rule of thumb is if your function is over a screen full, then break it into subroutines.

1. All input values should be echoed in a readable manner unless otherwise indicated.

2. The program output should be readable and clearly labelled. Headings should be used when appropriate.

3. Finally, of course, your program should produce correct results!