Program Style Guidelines for CS 1440


In general, the goal in programming is to write clear, readable programs that are as efficient as possible and solve a given problem. A program is not only a means of communicating with the computer, but is also a means of communicating with other people, including yourself. A program should be written so that a person who has not seen the program before, but knows the language, can read and understand the code.

The following guidelines will be used in grading programs for CS 1440 and will help you in achieving the goal of writing readable programs. Other courses that you take later in your career will indubitably tell you to adhere to some style guidelines. Those guidelines will probably be very similar to these, but they may not be the same.

Visual Clarity

Program Outline

The file containing the main function should have the following basic outline:
  1. Program heading comments
  2. #include statements
  3. Function prototypes
  4. Main function implementation
  5. Function heading comment and function implementation for each function

Indentation

Use a uniform indentation scheme (always indent the same way) to indicate statements within control structures, nesting of control structures, and statement continuation (if a statement won't fit on one line). Indentation of spaces is usual; much less is not enough and much more doesn't leave room for deep nesting. Avoid putting more than one statement on a line.

Spacing

Use spacing within a line to make it more readable. Use blanks around operators and other delimiters, after each comma in a list of items, and anywhere else that makes a program more readable. Do not put line breaks in the middle of quoted strings. Do not use very long lines in your program. There are still many display devices on which lines longer than about 80 characters are difficult to read. SOme examples,
    int    next_index       = 3;
    int    currentIndex     = 2;
    char   do_again         = 'y';
    char   currentCharacter = 'A';
    Widget myWidget         = new Widget();

Braces

All braces should line up with the current level of indention. Braces may follow a control structure or appear on the next line.
    i = 0;
    sum = 0;
    while (i < 10)
    {
        while (j < 10)
        {
            sum = sum  +  i * j;
            ++j;       
        }
        ++i;
    }
Or
    i = 0;
    sum = 0;
    while (i < 10)  {
        while (j < 10)  {
            sum = sum  +  i * j;
            ++j;
        }
        ++i;
    }

For some kinds of conditional code, avoiding braces and making things line up vertically can improve readability. For example,
  if (weight <= 1.0)            price = 0.37;
  else if (weight <= 2.0)       price = 0.60;
  else if (weigth <= 3.0)       price = 0.83;
  else if (weight <= 4.0)       price = 1.06;
  else                          price = 2.99;
as opposed to
       if (weight <= 1.0)
       {
              price = 0.37;
       }
       else if (weight <= 2.0)
       {
              price = 0.60;
       }
       else if (weigth <= 3.0)
       {
              price = 0.83;
       }
       else if (weight <= 4.0)
       {
              price = 1.06;
       }
       else                      
       {
              price = 2.99;
       }

Program and function heading comments

Every program file, include file, and function within the program should be prefaced by a heading comment.
  1. Program Files heading
     // 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>
    
  2. Function heading
     // Function:    <Function Name>
     // Purpose:     <A brief description of the function's behavior>
     // 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>
    
         // a gets the value of b
for the statement "a = b;" is useless.

Upper/lower case

Normally we shall use lower case exclusively, except for names of constants which should be all uppercase.

Understandability

Names

The names of variables, functions, types, etc. should be descriptive of their purpose. Don't be afraid to use longer names to avoid names that are short and cryptic. Some general rules:
  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.
  6. Use the underscore character to separate words within a name.
  7. Be consistant in use of Upper case. Generally, we only use lower case.

Modularity

A program is easier to design/write/debug/maintain when it is broken into a group of smaller units that solve particular parts of the whole problem. All functions should be designed to do one task only. Thus, functions should be relatively small (say 40 lines or less). Any task that is repeated at several points in the program should be put in a separate function. Even tasks that are done only once, like initialization, can be put in a separate function to simplify the code. Your main function will normally be a few function calls and perhaps some simple control structures.

---
File time-stamp: Friday, 20-Feb-2004 08:48:10 EST