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 313.
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 'num' as in 'numStudents'.
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.
Whether writing code or having your program produce output, it should
always fit into an 80 character wide screen. You should never let a statement
wrap down to the beginning of the next line, since it obscures the indentation.
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 section number
Your UMBC e-mail address
A description of the contents of the file
For example
/*****************************************
** File: proj4.c
** Author: Bob Smith
** Date: 4/22/06
** Section:304
** E-mail: bsmith22@gl.umbc.edu
**
** This file contains the main driver program for project 4.
** 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. proj4.h -- prototypes for the functions defined in this file
** 2. chars.c -- functions that count each type of character & words
** 3. chars.h -- prototypes for the functions defined in chars.c
**
***********************************************/
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 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
**************************************************/
Function header comments are also required above the function prototypes,
since the header file is designed to be used as an interface.
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]++;
}
}
Endline comments are not allowed :
for (i = 0; i < ARRAYSIZE; i++) /* check every element of the array */
Top of PageLast Modified: Thursday, 08-Jul-2010 09:21:24 EDT
