ICS212 C Coding Standards

The following are the coding standards that you must follow when writing code for this course. Coding standards for C are not as well-established as they are for Java. Since there are a lot of different preferences out there, these standards often give you 2 or 3 options to choose from. However, you must choose one of the options listed here. (If you really really want to follow a different style that has an established usage in a particular real-world coding community, check with the TA.)

General

• Whichever style you choose, be consistent throughout your code.
• When editing or expanding existing code, follow the existing style whenever possible.
• When an assignment (or other specification) specifies a particular name for a variable, function, type, file, etc., use exactly that name. Remember that case matters.
• [This document may be expanded over the semester.]

File Structure

A source code file should contain the following sections (some of which may be empty), separated by 1 or 2 blank lines, in the following order:

• Documentation for the file (module) in general. Include your name as author. (Creation date and assignment are also good things to include.)
• #includes (system library <headers> followed by any local "headers")
• #defines
• extern variables and function declarations
• global variables
• functions

Comments

Documentation (Outside of functions)

Functions and any global variables should be documented with a comment block. This documentation should describe the function (or variable) in enough detail that someone could sufficiently understand what it does in all situations without reading any of its code.

If the file contains more than one function, an overview summary of the file/module should be given at the very top of the file. (If a file contains only a single method--such as main--the file header comment and the single function's documentation will likely say the same thing. In this case, one or the other may be omitted.)

Each function should then be immediately preceded by the documentation block. This documentation should contain the following information:

• An initial one-sentence overview summary of what the function does.
• The parameters of the function: What do they represent? What is the range of legal values for each one? What does the function do if passed values that are outside of that legal range?
• What does the function do? Does it affect any global variables? If so, how? (Do not include implementation-level details of how the function works though. It doesn't matter what local variables you have, whether you used a while loop or a for loop, or anything like that.)
• What the method returns (if anything).

You may structure this documentation content using the format you prefer. For example, you can use a logical paragraph structure like the lab examples; or you can explictly label the sections regarding Parameters, Returns, etc as done on the lecture slides. You are not required to restate anything that is completely obvious from the function prototype, including the return type, the function's name, and the name of the parameters. Your goal in documentation is to add to or explain what is already apparent from the prototype.

Documentation comment blocks should clearly stand out from the rest of the code. Examples:

/*
 * Note the column of *s to make the comment stand out.  This the TA's 
 * preferred style.
 * 
 * Starting the block in JavaDoc style with /** would also be acceptable.
 * Such a comment can be extracted from the code by tools such as Doxygen.  
 */

/////////////////////////////////////////////////////////////////////
// A comment block, as often used in the lecture slides.           //
// These make comments much more obvious but can also make them    //
// harder to edit or reformat later.                               //
/////////////////////////////////////////////////////////////////////

//
// C++-style comment block.  Note the initial and ending blank lines to help
// differentiate this as a documentation-level (rather than an implementation-
// level) comment.  Using three ///s would be acceptable too.
// 

See the example files below for examples of real documentation content.

Comments (Inside functions)

When writing functions, you should break the code up into logical sections of about 3 to 7 lines each. Each section should have a short (usually one-line) comment explaining what the purpose or goal of the following code is. The comment should be indented to the same level as the code it refers to.

// A C++-style one-line comment.

/* A C-style one-line comment. */

The TA prefers using the //C++-style within functions. This makes it very easy to then comment-out chunks of code when debugging using /* comments */.

Structure and White Space

• Indent your code such that it is easy to match up { opening and closing } curly braces and thus to see where blocks start and end. There are a great many brace-indent styles out there. In this course, please limit yourself to either:

  One True Brace Style: Opening braces are always at the end of the line of the associated control structure. Closing braces are on their own line, indented so as to line up with the first character in the line containing the matching opening brace. Example:

  void printRoom(int playerX, int playerY, int exitX, int exitY) {
  
    int row, col;
    for (row = 0; row < HEIGHT; row++) {
      for (col = 0; col < WIDTH; col++) {
        if (row == playerY && col == playerX) {
          printf ("%c", PLAYER);
        }else if (row == exitY && col == exitX) {
          printf ("%c", EXIT);
        }else {
          printf("%c", FLOOR);
        }
      }
      printf("\n");  //end row
    }
  }
  

  Allman Style: Open braces go on their own line, indented to be even with the first character of the associated control structure line above. Closing braces also go on their own line, indented to line up with the associated opening brace.

  void printRoom(int playerX, int playerY, int exitX, int exitY) 
  {
    int row, col;
    for (row = 0; row < HEIGHT; row++) 
    {
      for (col = 0; col < WIDTH; col++) 
      {
        if (row == playerY && col == playerX) 
        {
          printf ("%c", PLAYER);
        }
        else if (row == exitY && col == exitX) 
        {
          printf ("%c", EXIT);
        }
        else 
        {
          printf("%c", FLOOR);
        }
      }
      printf("\n");  //end row
    }
  }
  

• Use braces with all blocks, even one-line if, while, for, etc.
  (Exception: If you put the short one-line body on the same line as the test, you may omit the braces:

    if (input == 'd') playerX++;
  
    while (getchar() != '\n');
  

  In these examples, reformatting would be required to add another line to the loop, so it will be easy to notice the missing braces. Still, better to avoid this style when possible.)
• Use either 2 spaces, 4 spaces, or a tab character for indenting. Be consistent. Do not mix tabs and spaces! If your IDE inserts one kind and you use another, change your IDE's settings.
• Keep code lines to 80 characters or less in length. (Try to break the line after a binary operator. Indent the partial line an extra amount to show that it is not its own line.)
• Put spaces around binary operators. So:

  ave = total / count;
  

  not:

  ave=total/count;
  

• Do not put spaces around these operators: . -> ::
• Put a space between a keyword and an opening (, but not between a function call and its opening (. This makes function calls obvious. Also, return does not usually need parentheses if it is not a complicated expression. So:

    if (rollback(lastChar) == '\n') {
      return done;
  

  not:

    if(rollback (lastChar) == '\n') {
      return(done);
  

Identifiers

• Use descriptive, relevant names for your variables, function names, constants, and filenames. They should not be overly short or abbreviated. (Early C violated this rule and we're still suffering for it. From the standard library: atoi, printf, strrchr, strpbrk, etc. Don't emulate this!)
• Variable names should start with a lowercase letter.
• Constants and macro names should be in ALL_CAPS
• If using more than one word as part of your variable or function name, use either camelCase or separate the words with underscores:

    tallestTreeInForest
    tallest_tree_outside_forest
  

Examples

• maze.c