Program Style Guidelines

Visual Clarity

Program Outline

1. Program heading comments
2. #include statements
3. Constant global variables
4. Heading comment and implementation for each function or method

Indentation

Braces

    for (int i = 0; i < 10; ++i)
    {
        for (int j = 0; j < 10; ++j)
        {
            foo[i][j] = i + j;
        }
    }

    for (int i = 0; i < 10; ++i) {
        for (int j = 0; j < 10; ++j) {
            foo[i][j] = i + j;
        }
    }

    for (int i = 0; i < 10; ++i)
        {
        for (int j = 0; j < 10; ++j)
            {
            foo[i][j] = i + j;
            }
        }

Spacing

    int    currentIndex     = 2;
    char   currentCharacter = 'A';
    Widget myWidget         = new Widget();

Blank lines

1. Around the body of compound statements,
2. To separate sequential statements into logical groups,
3. To separate a control structure (if, while, for) from complex surroundings.

Line Length

    if (thisVariable      == thatVariable    ||
        someOtherVariable == anotherVariable) {
        ...
    }

    someObject.someMethod(thisParameter,      thatParameter,
                          someOtherParameter, anotherParameter);

Program, class, method, and function heading comments

1. Main program heading

    // Program:     <Program Name>
    // Author:      <Your Name>
    // Date:        <Date program was started>
    // Assignment:  <Which Program>
    // Purpose:     <A brief description of what the program does and,
    //               at a very basic level, how it does it>
    // Input:       <Describe the input expected by the program>
    // Output:      <Describe the output produced by the program>
    // Related
    // Files:       <Other files needed - header files, source files>
    // Functions:   <A list of the functions used in the program 
    //               with a brief description of each function>
    // History:     <Optional - list of modifications following 
    //               the initial implementation>
   

2. Heading for files containing other functions and for include files

    // Filename:   <Filename>
    // Author:     <Your Name>
    // Date:       <Date code was started>
    // Assignment: <Which Program>
    // Purpose:    <A brief description of what type of functions are in
    //              the file and how they relate to other program files> 
    // Related
    // Files:      <Other files needed - header files, source files>
    // Functions:  <A list of the functions defined in this file
    //              with a brief description each function>
    // History:    <Optional - list of modifications following 
    //              the initial implementation>
   

3. Class Heading

   // Class:         <Class Name>
   // Purpose:       <Description of the object this class models>
   // Author:        <Your Name>
   // Date:          <Date code was started>
   // Superclasses:  <List of superclasses>
   // Subclasses:    <List of known subclasses>
   // Associated
   // Classes:       <List of classes that are associated with this class>
   

4. Method Heading

    // Method:      <ClassName::MethodName>
    // Purpose:     <A brief description of the method's behavior>
    // Author:      <Your name or whoever wrote the method>
    // Date:        <Date the method was written>
    // Parameters:  <List of the parameters expected by the method and
    //               a description of what each one means logically>
    // Returns:     <Value, if any, the method returns>
    // Pre-
    // Conditions:  <A list of conditions that must be true before
    //               the method is invoked>
    // Post-
    // Conditions:  <A list of conditions that will be true after the
    //               the method returns>
   

5. Function Heading

    // Function:    <Function Name>
    // Purpose:     <A brief description of the function's behavior>
    // Author:      <Your name or whoever wrote the function>
    // Date:        <Date the function was written>
    // Parameters:  <List of the parameters expected by the function and 
    //               a description of what each one means logically>
    // Returns:     <Value, if any, the function returns>
    // Pre-
    // Conditions:  <A list of conditions that must be true before
    //               the function is invoked>
    // Post-
    // Conditions:  <A list of conditions that will be true after the
    //               the function returns>
   

Inline comments

1. Each constant and variable should be placed on a separate line and should be followed by a comment which describes how it is used in the program. Recall that formal parameters are documented in the function header, although it is okay to include inline documentation of them as well.
2. The ending of a control structure in a complex section of code should be marked by a comment indented at the same level as the beginning of the control structure. e.g., the end of the body of a nested if statement or the else part of nested if's.
3. Unclear program statements should be documented. These comments should describe the logical effect of the statements or help the programmer remember obscure facts. In the following example, the specified comment is useless.

   // a gets the value of b
   a = b;
   

4. Do not apply creativity to your commenting. Use your creativity to solve the problem at hand, not to document your code. Make comments meaningful.

Upper/lower Case

1. Use all uppercase characters for constants:

       static const int MAX_BUFFER_SIZE = 10; 

2. All class and struct names begin with an uppercase letter:

       class  Widget
       struct Node
   

3. Multi-word class and struct names begin with an uppercase letter and the first letter of each word is uppercase

       class  BigInteger
       struct ListNode
   

4. All function, method, and variable names begin with with a lowercase letter

       int paint();
       int count;
   

5. Multi-word function, method, and variable names begin with a lowercase letter and the first letter of each word is uppercase

       int getCurrentIndex();
       int currentIndex;
   

Understandability

Names

1. Function names can be long and descriptive since they usually appear infrequently and describe an action rather than an object.
2. Type names can be long and descriptive since they usually appear only in variable or parameter declarations.
3. Variable names up to 10 characters usually provide a sufficient description without cluttering up expressions.
4. Variables used as array subscripts should be shorter if possible.
5. Variables used only as counters, loop controls, etc., can be as short as 1 to 3 characters in length.

"Magic Constants"

    const int MAX = 20;

Complexity

Modularity

Global variables

Runtime behavior

Robustness

Error handling

Output formatting

Generality