Spring '06

CSEE | 201 | 201 S'06 | lectures | news | help

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. Neatness counts ! ! ! At UMBC, the following standards have been created and are followed in 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 of Whitespace

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

Use of Braces


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.
  1. The file name
  2. Your name
  3. The date the file was created
  4. Your section number
  5. Your UMBC e-mail address
  6. A description of the contents of the file
For example /***************************************** ** File: proj1.c ** Author: Bob Smith ** Date: 6/22/99 ** Section:304 ** E-mail: ** ** 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:
  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. 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

"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 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]++; } }

Comments for #defines and variables

#defines may be commented on the same line as they occur. Such comments should be aligned with the comments for other #defines. Once again -- Neatness Counts ! !
For example #define NUMSTUDENTS 55 /* number of students in the class */ #define NUMSECTIONS 12 /* number of sections of CMSC201 */ #define NUMTAS 8 /* number of graduate student TAs */ variables may be commented in the same style as #defines
IF THEY ARE DEFINED ONE PER LINE as in this example int total; /* total students this section */ FIlE *ifp; /* input file pointer */ double average; /* class's final exam average */ This style of commenting is called end-line commenting. It is acceptable ONLY for variables and #defines and not allowed for other sections of code.

I would suggest that if you are using meaningful identifiers (variable and symbolic constant names), then commenting them in this manner is redundant, and therefor, completely unnecessary.

CSEE | 201 | 201 S'06 | lectures | news | help

Monday, 23-Jan-2006 09:13:42 EST