CMSC 201 - C Coding Standards

General Comments

Every programming department has a some set of standards or conventions that programmers are expected to follow. The purpose of these standards is make programs readable and maintainable. After all, you may be the programmer who maintains your own code more than 6 months after having written the original. While no two programming departments standards/conventions may be the same, it is important that all members of the department follow the same standards. Neatnes counts!!!

At UMBC, the following standards have been created and are followed in CMSC 201, CMSC 202 and CMSC 341. Part of every project grade is based upon how well these standards are followed.

Naming Conventions

• Use meaningful variable names!!
  For example, if your program needs a variable to represent the radius of a circle, call it 'radius', NOT 'r' and NOT 'rad'. The use of single letter variables is forbidden, except as simple 'for' loop indices.
• Begin variable names with lowercase letters
• Begin function names with uppercase letters
• Use all uppercase for symbolic constants (#define)
• Do not use global variables
• Be consistent!
• Separate "words" within identifiers with underscores or mixed upper and lowercase.
• Examples:
  2-"word" variable name: baudRate or baud_Rate
  2-"word" function name: ProcessError or Process_Error

Use of Whitespace

The prudent use of whitespace (blank lines as well as spaces and tabs) goes a long way to making your program readable.

• Use blank lines to separate major parts of a source file or function.
• Separate declarations from executable statements with a blank line.
• If possible, configure text editor to use spaces rather than tabs.
• Use tab stops of 3 or 4 spaces
• Preprocessor directives, function prototypes, and headers of function definitions begin in column 1.
• All statements in the body of a function are indented one tab stop; statements inside of a loop or part of an "if" structure are indented further.
• Use spaces around all operators. For example, write x = y + 5;, NOT x=y+5;

Use of Braces

• Always use braces to mark the beginning and end of a loop or "if" structure, even when not required.

Comments

Comments are the programmers main source of documentation. Comments for files, functions and code are described below.

• Every source file (.c and .h files) should contain an opening comment describing the contents of the file and other pertinent information (file name, author's name, creation date, history of changes, special notes or compilation instructions). For example /***************************************** ** File: proj1.c ** Author: Bob Smith ** Date: 6/22/99 ** ** This file contains the main driver program for project 1. ** This program reads the file specified as the first command line ** argument, counts the number of words, spaces, and characters and ** displays the results in the format specified in the project description ** ** Other files required are ** 1. chars.c -- routines that count each type of character ** 2. words.c -- routines that count each word ** 3. proj1.h -- prototypes for all functions needed by this file ** ***********************************************/

• Each function must have a header comment includes the following:
  1. function name
  2. a description of what the function does
  3. a description of the function's inputs
  4. a description of the function's outputs
  5. a description of each parameter and the function's return value if not included above
  6. side effect of the function (if any -- this should be rare)
  For example: /************************************************ ** CircleArea -- ** This function calculates the area of a circle ** with the specified radius ** Inputs: the circle's radius as a parameter ** Output: the circle's area as the return value **************************************************/

• "In-line" comments are used to clarify what your code does, NOT how it does it. Well structured code will be broken into logical sections that perform a simple task. Each of these sections of code (typically starting with and 'if' statement, or a loop or a 'switch' should be documented. A particularly important line of code should also be commented. Do not comment every line of code. Trivial comments (/** increment x **/) are worse than no comments at all.
  An in-line comment appears above the code to which is applies and is indented to the same level as the code. For example: /* check every element of the array */ for (i = 0; i < ARRAYSIZE; i++) { /* if it's odd, add one ** if even, do nothing */ if (array[i] % 2 == 1) { array[i]++; } }

Monday, 21-Jun-1999