CMSC 104 - C Coding Standards
General Comments
Every programming department has 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 six months after having written the
original. While no two programming department's standards/conventions may
be the same, it is important that all members of the department follow
the same standards. Neatness counts!!! At UMBC, the following standards
have been created and are followed in CMSC 104 and CMSC 201.
Part of every project grade is based upon how well these standards are
followed.
It is your responsiblity to understand these standards. If you have any
questions, ask your instructor, any of the TAs or the Help Center.
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. The
use of obvious, common, meaningful abbreviations is permitted. For example,
'number' can be abbreviated as 'nr' as in 'nrStudents'.
-
Begin variable names with lowercase letters
-
Begin function names with uppercase letters
-
Use all uppercase for symbolic constants (#define)
-
Use all uppercase for typedefs
-
Do not use global variables
-
Be consistent!
-
Separate "words" within identifiers with underscores or mixed upper and
lowercase. Examples:
2-"word" variable name: grandTotal or grand_total
2-"word" function name: ProcessError or Process_Error
Use of Whitespace
The prudent use of whitespace (blank lines as well as space) 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.
-
DO NOT use tabs (unless your editor changes TABs to 3 or 4 SPACEs). TABs
may be interpreted differently by different editors.
-
Use 3 or 4 spaces for each level of indentation
-
Preprocessor directives, function prototypes, and headers of function definitions
begin in column 1.
-
All statements in the body of a function are indented 3 or 4 spaces. 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;
-
Using the emacs or xemacs editor along with the the .emacs file provided
for you will automatically indent your code appropriately.
Use of Braces
-
Always use braces to mark the beginning and end of a loop or "if" structure,
even when not required.
-
See the indentation standard for appropriate
placement of braces.
Comments
Comments are the programmers main source of documentation. Comments for
files, functions and code are described below.
File Header Comments
EVERY source file (.c and .h files) should contain an opening comment
describing the contents of the file and other pertinent information. This
"file header comment" MUST include the following information.
-
The file name
-
Your name
-
The date the file was created
-
Your SSN (last 4-digits okay i.e. xxx-xx-1234)
-
Your section number
-
Your UMBC e-mail address
-
A description of what the program does
For example,
/*****************************************
** File: proj1.c
** Author: Bob Smith
** Date: 6/22/99
** SSN: 123-45-67689
** Section:304
** E-mail: bsmith22@gl.umbc.edu
**
** 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
**
***********************************************/
Function Header Comments
EACH FUNCTION must have a header comment that includes the following:
-
function name
-
a description of what the function does
-
a description of the function's inputs
-
a description of the function's outputs
-
side effect(s) 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
"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 an '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 it 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]++;
}
}
Comments for #defines and Variables
#defines may be commented on the same line as which they occur.
Such comments should be aligned with the comments for other #defines. Once
again -- neatness counts!
For example,
#define NRSTUDENTS 35 /* nr of students in the class */
#define NRSECTIONS 4 /* of CMSC201 */
#define NRTAS 5 /* nr graduate student TAs */
Variables may be commented in the same style as #defines
IF THEY ARE DEFINED ONE PER LINE as in the example below.
int total; /* total students this section */
FIlE *ifp; /* input file pointer */
double average; /* class's final exam average */