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.)


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 (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:

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