BU CAS CS 113
Introduction to Computer Science II with Intensive C
Fall 1997

This convention is based on the implicit conventions used by Eric Roberts in his text books The Art and Science of C, and Programming Abstractions in C. 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 one of the texts mentioned above.

Names

• Function names: always begin with upper case, e.g., First().

• Variable names: start with a lower case letter, and, for pointer types, end with "P" or "Ptr", e.g., nextP.

• Type names: first character should be lower case, and the suffix must be "T" or "Type", e.g., listNodeT.

• Constants: You have two choices, but you should not mix them, use one consistently. Either
  1. all constansts 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. This is the method used in The Art and Science of C and Programming Abstractions by Eric Roberts.
  (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.

• Multi-word names, for entities other than all capitalizeed constants, should have every word other than the first one capitalized, e.g., InsertAfterElem(), myFavoriteInteger. For ALL CAPS constansts separate words with an underscore.

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 as abbreviations, instead, if your names are getting long you may eliminate vowels (e.g., frstElmnt), or use an unambiguous prefix (e.g., firstElem), but NOT fe.

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


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

• 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 of Roberts:

  /*
   * 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

Specific Guidelines for the Boiler Plate:

• The name of the file must be given at the top and bottom of the file, ala Standish, 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

Avoid 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

Make judicious use of White Space