CS1711 C++ Programming Standards

PURPOSE

FILE NAMES AND C++ ENVIRONMENT

INTRODUCTORY DOCUMENTATION

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

An example of the required format is as follows:

//******************************************************************* 
//                                                                    
//  Program:  Converting temperatures                                           
//                                                                     
//  Author:  Jane Doe, jnde@mta.ca
//                                                                    
//  Description:  brief description of the program                    
//                                                                    
//  Date:  September 28, 1999
//
//  Course Information: CS 1711, Section A, Assignment 2, Problem 1
//
//  Filename: convert.cpp 
//                                                                    
//*******************************************************************

DECLARATIONS

1. You must 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. Each identifier declaration (including function declarations) must be accompanied by a comment that explains its use.

3. Classes and Structs must begin with a capital letter (for example, Date, Vehicle, Software_engineer).

4. Variable names must start with lower case letters (for example, student, temperature, weight, salary). Separate any multiple words in a variable name by using upper case letters (for example payRate, fuelLevel, serialNumber). Note: We adopt this standard to conform with your text. Many authors use underscore for this purpose (e.g. pay_rate, serial_number.)

5. Constant values used in your program will be given in const declarations. Constant identifiers must always appear in upper case 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
   

6. Do not declare globally-visible variables. Globally-visible constants, enumerated types, classes, structures, and file names are permitted.

GENERAL RULES

1. Each constant and variable declaration must 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 circuitName[NAME_LENGTH];  // name of the circuit 
   

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

   left = nextLeft;    right = nextRight;
   

   use

   left  = nextLeft;     // move to the left
   right = nextRight;    // move to the right
   

   Occasionally this may be violated, for example for index initialization.

3. Each function must be preceded by a comment block describing its purpose, parameter(s), and the function(s) it calls. The format to be used is as follows:

   //******************************************************************
   //                                                                  
   //  Function: findSpaceCost
   //                                                                  
   //  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 cargoRates
   //                                                                  
   //******************************************************************
   

4. Comment blocks must be set apart from the code by at least one blank line, making it easy to see where the code ends and comment begins.

5. The main function should begin with
   

   void main ()
   

   even though that will lead to a warning from some C++ compilers, and notice that your text uses the common

   int main ()
   

6. Function prototypes must include the type and name of each parameter:
   

   float expo (float value, int exponent);
   

7. Use the endl construction (instead of \n) to indicate end-of-line. For example, use
   

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

   instead of
   

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

FORMATTING AND COMMENTING OF STATEMENTS

Use whitespace (blank lines and spaces on lines) liberally!
Use parentheses liberally!!

The body of a control structure, such as an if, a switch, a while, a do, or a for statement, must be indented. You may use from 3 to 6 spaces per level of indentation.

Each multiple line control structure body must be surrounded by braces on a separate line. If the number of lines in the control structure body exceeds 5 there must be a comment indicating the origin of the structure.

Thus, the main constructs will appear as follows in your programs:

if statement

if (expression)
  {
   statements
  }

if (expression)
  {
   statements
  }  // end if (expression)

if-else statement

if (expression)
  {
   statements
  }
else
  {
   statements
  } // end if (expression)
    
switch statement

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;
  }  // end switch (selector)

    

while statement

while (expression)
  {
   statements
  }  // end while (expression)

do-while statement

do  // while (expression)
  {
   statements
  }
while (expression);

for statement

for (initialization; test; increment)
  {
   statements
  } // end for (initialization)

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. In many cases the assignment will specify functions and their parameters.

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

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

OUTPUT

1. All input values must 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!

Return to CS1711 page