CIS 150 Coding Standard

Different instructors, like different organizations, have their own coding standards which you must follow. In general, these tend to be very similar to each other and usually reflect industry standards. We want you to code in a style that is recognized and respected in the field. We also want your code to be easy to read, debug, and maintain. The coding standards help to achieve these goals.

Basic program structure

Your programs should be organized as follows:

• main program documentation
• include directives
• constants
• class definitions
• function prototypes
• global variables (these should be rare at best)
• main function
• all other functions

Documentation

• The main program documentation should be a block comment including your name, the date, the course number, the assignment number, and a description of what the program does. It should also include what is needed for input and for output. Any additional notes that would be helpful should be included after the main information. Samples will be provided in class and online, and will get more detailed as the course progresses.
• Each function should have its own block comment documentation preceding it which gives its prototype, describes what the arguments to this function are, what the function returns, and a description of what the function does.
• Add comments to any section of code that is not obvious explaining what is being done.
• Do not hand in code where sections of code have been commented out as if they are documenting your failures. Code that doesn't work should be removed unless it is needed for valid documentation purposes.

Capitalization and naming

• Variable and function names should be lowercase. If they are composed of multiple word parts, each starting letter after the first should be capitalized. This is called camel-casing. Examples: num, payRate, hoursWorked.
• Symbolic constant names should be in all caps. Words should be separated using an underscore. Example: TAX_RATE.
• Variable names should be descriptive. Example: hoursWorked, NOT hw. An exception is simple loop counters which may be a single letter or abbreviation.
• Function names should be descriptive of their purpose. Example: calcGrossPay().

Indentation

• Indentation must be used for readability. All code blocks must be indented either three or four spaces beyond the previous level.
• Code blocks are delimited using the curly braces, "{" and "}".
• Your indentation should use spaces and NOT tabs. This may require changing your editor/IDE settings.
• The bodies of all for, while, and do/while loops must be indented.
• The bodies of all if and if/else branches must be indented.
• The bodies of all functions must be indented.
• There are three main styles for where the curly braces are placed. This course accepts two different styles. Strangely, NIU uses the third style that this course does not accept. Different organizations have different standards. Get used to it. In the examples below, this course accepts either of the first two styles. Personally, the instructor prefers the first style, which used to be referred to as the Bell Labs style.
• Curly brace placement examples:

   Style 1            Style 2         Style 3 (NIU)
  -----------        ---------        -------------
  if (cond) {        if (cond)        if (cond)
     stmt1;          {                  {
     stmt2;             stmt1;            stmt1;
  } else {              stmt2;            stmt2;
     stmt3;          }                  }
  }                  else             else
                     {                  {
                        stmt3;            stmt3;
                     }                  }
                     
   Style 1            Style 2         Style 3 (NIU)
  -----------        ---------        -------------
  while (cond) {     while (cond)     while (cond)
     stmt1;          {                  {
     stmt2;             stmt1;            stmt1;
  }                     stmt2;            stmt2;
                     }                  }
  

White space

• You may use blank lines to separate statements to make code more readable, but do not use white space excessively.
• DO NOT double space your code. It's annoying and makes the code harder to read and maintain.

Miscellaneous

• In this couse, the use of proper namespaces is considered important. Since the statement "using namespace std;" makes namespaces close to worthless, it is not allowed in your programs for this class unless specifically allowed by the instructor. Instead, your programs should use specific "using" statements as needed. See the example programs for actual C++ examples.