Chris Pollett>Old Classes>CS112, Spring 1998>Coding Conventions

This is a compulsory set of programming rules to foster the habit of following some convention consistently. These conventions are designed to improve code readability, on the premises that far more human time is spent reading code than writing it, that far more human time is spent modifying existing code than writing entire programs from scratch, that far more code is written by groups of people than by single individuals. In particular, following these rules will make it easier for the grader to grade your work and the instructors to assist you if you are having difficulty.

This convention is modified from the conventions used in Randy Pruim's CS113 class for Fall 1997. When there is a difference between what is done in the books and what is outlined here, this takes precedence. If you have a question about something not covered here, imitate the code from Standish.

Names

As part of program documentation, names must clearly indicate both the kind of thing being named and its role in the program.

• Function names: always begin with upper case, e.g., First().
• Variable names: one has two choices, and you should choose one and follow it consistently. (1) Start with a lower case letter and then capitalize the letters at word breaks, and, for pointer types, end with "P" or "Ptr", e.g., nextNumber, nextP. (2) Variable names only one word long can begin either with a lower case or an upper case and thereafter are lower case. Multi-word variable names follow the function name convention. e.g., sum SumOne SumPtr
• Type names: follow the variable names capitalization convention then add the suffix "T" or "Type", e.g., listNodeT or ListNodeT .
• Constants: You again have two choices, but you should not mix them, use one consistently. Either
  1. all constants should be all capital letters, with multiple words separated by underscore "_", e.g., MAX_SIZE, or
  2. all constants should begin with a capital letter followed by lower-case letters, just like function names.
  (One exception, constants derived from file names and used solely for the purpose of identifying read code, like _string_h, may be use lower case.)
• File variables: lower-case, just like other variables.
• External file names: use all lower-case letters. When possible use 8.3 (DOS compatible) names, e.g., myfile.txt.

In addition to following the guidelines above to indicate what kind of thing you are naming, a name should be chosen which will reveal the meaning or use of that thing in your program.

• In general, choose English words which describe the thing being named.
• Avoid using lots of one- and two- character names like x or b2.
• Never use acronyms for long words you may eliminate vowels (e.g., frstElmnt), or use an unambiguous prefix (e.g., firstElem), but NOT fe.

Indentation

Maintain consistent indentation throughout your code. Examples:

if (condition){
    statements
} else {
    statements
}			/* end if ... */


for (...){
    statements
}  			/* end for ... */

Rightward Drift. As you get more and more deeply nested block of code, indentation pushes you farther and farther to the right, until eventually you have hardly any room to write a line of code. To avoid this, you can do two things:

• Use a modest size indentation. Four spaces is probably optimal. If you anticipate problems with rightward drift, you could even try two or three, although this is not as easy to read.
• Use a function. Often rightward drift is an indication that you should consider replacing a block of code with a call to a function which carries out the instructions in that block. This is especially true if you anticipate using the same or a similar block elsewhere. This can improve readability of the program as well, since the reader can think of a large block of code in terms of one function call, only bothering with the details of the function when needed.

Comments

Comments should help the reader of your code to understand it. In the case of a programming course, they also serve to convince the grader that you grasp the what, how and why of your code (as opposed to having hacked it into working). Like any other form of expression, it should not be flowery or repetitive. In particular observe the following guidelines

• All internal documentation must be written in English, not in C. Avoid comments that simply rephrase your code in English, without summarizing it or adding any information.
• For each variable, give a one-line comment stating the use of the variable. These may follow the variable declaration, as in:

    int i;				/* loop variable */
    for (i = 0; i < sizeOfArray; i++){
        someArray[i] = 0;
    }
  
  

  Or you may use a comment block to identify the use of several variables together.
• Before each major section of the program, give the purpose of that section.
• At the end of statement blocks unless the block is only a couple lines long, there should be a comment indicating which block is being ended. See the examples above.
• Before each function prototype, describe the function and give the inputs, output and error conditions of the function. Follow the format:

/*
 * Function: FunctionName
 * Usage: t = FunctionName(proposedName) 
 * -------------------------------------
 * This function returns a boolean value which is true if proposedName is
 * a name contains a string which follows the guidelines given in this 
 * convention for naming functions, otherwise it returns false.
 *
 * In general, comment here on anything which would be of use for the 
 * _caller_ of the function. You may comment on the types of the variables 
 * (as I did in * the paragraph above).  Sometimes this may be unnecessary, 
 * if it is clear from the name of the function and its parameters and the 
 * comments are not too lengthy, since the prototype will follow.  Other times 
 * it might be nice to list the variables and what they mean, just as you
 * would in the main program.
 */

boolean FunctionName(string proposedName);

• Comment Blocks like the one used above should have a running line of asterisks which clearly identifies the block as a comment, even if the beginning or end of the comment is not visible on the page or screen.

Standard Boiler Plate

Each source file must have a standard "boiler plate". This boiler plate must include your name, the class (CS 112), the assignment number, due date, the problem number, and a brief description of the what the code in the file does. You should outline the method you used to solve the problem, describe the variables and data-structures used in the program, any error conditions which might be encountered in the solution, and how these error conditions are handled by the solution, any known deficiencies (documented bugs, cases which the program does not handle, etc.), and a separate list of enhancements (any features not required in the assignment) if there are any.

Specific Guidelines for the Boiler Plate:

• The name of the file must be given at the top and bottom of the file, so that if several files are concatenated, it will still be possible to identify the beginning and end of each file and its original name.
• The boiler plate for a main program MUST include what the inputs are (arguments to the program, files used by the program, and values obtained via standard input), how the input must be formatted, and what the output is.
• The boiler plate for a program should be in paragraph form and in standard English. The boiler plate for a package (in the header file) should be mostly English, but may use a bit of C code or pseudo-code to demonstrate to the reader how the functions are to be called or to highlight algorithmic details which could be important to a programmer using the package.
• In programs which are built from several files, keep the reader in mind when you decide what comments go in which file.
  • The boiler plate for a main program is intended primarily for the user of the program. It is like the documentation you get along with professional software (but don't emulate professional documentation too much, often it is quite poor.)
  • The boiler plate in a header file should include information useful for someone intending to use the package in another program, i.e., it should be mostly about the interface and performance.
  • The boiler plate in the implementation files of a package should be written for the sake of a future programmer who may want to correct, modify, or enhance your package. It should include comments about overall structure, choice of data types, or any other things which would make your code easier for another programmer to read and modify.

Example

Here is a simple example of the program ave2f.c with a boiler plate included. (This program appears on page 47 of Robert's The Art and Science of C.) For a simple program such as this one, some of the comments may seem like overkill, but it will become increasingly important as our programs become more complicated.

You may imitate this style (here is a blank version which you can edit for your programs) or feel free to make up your own boiler plate style. If you decide to use your own boiler plate, use it consistently and be sure it includes everything required.

Avoid Global Variables!

Before you use global variables, consider first supplying pointers to variables so that functions can modify those variables by dereferencing the pointers. If that is not enough, then try static local variables, and, failing that, static global variables. Only when none of these work--a very rare event indeed--should you resort to plain global variables.

If you do use a global variable (plain or static) be sure to document carefully when, where (in which blocks of code), and why the variable is changed. One of the most difficult things to debug can be the overuse or improper use of global variables.

Keep Line Lengths Under 80 characters

On many machines and in many software packages, this is a standard line length. It makes it easier for others (like graders) to read and/or print your programs.

Make judicious use of White Space

Sometimes the simple insertion of a blank line here and there to help group a few lines of code which work together to achieve a subgoal can make the program much easier to read. But don't put in too much white space or the reader will not be able to see enough of the code at a time.