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 departments standards/conventions may be the same, it is important that all members of the department follow the same standards. Neatness counts!!!
Part of every assignment grade is based upon how well these standards are followed. It is your responsibility to understand these standards. If you have any questions, ask your instructor!
Naming Conventions
-
Use meaningful variable names! For example, if your
program needs a variable to represent the radius of a
circle, call
it
radius
, notr
and notrad
. The use of single letter variables is forbidden, except as simplefor
loop indices. The use of obvious, common, meaningful abbreviations is permitted. For example,number
can be abbreviated asnum
as innum_students
. - Begin variable names with lowercase letters
- Be very careful with global variables. You must justify any use of them.
- Be consistent!
-
Separate "words" within identifiers with
underscores or mixed upper and lowercase. Examples:
2-"word" variable name:
grandTotal
orgrand_total
2-"word" function name:
ProcessError
orProcess_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 variable declarations from executable statements with a blank line.
- For each level of indentation, use either tabs (preferred) or 4 spaces.
- Indent statements inside of a loop or part of an "if" structure.
-
Use spaces around all operators. For example,
x = y + 5
NOTx=y+5
- Try to limit your lines to no more than 79 characters. Break up long lines into separate lines when possible.
Use of Braces
- 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 project file should contain an opening comment describing the contents of the file and other pertinent information. This file header comment MUST include the following information.
- Your name
- Your email address
- A description of what the program does
/** * @author George Burdell (gburdell@umbc.edu) * @file * This file contains a program that gets two numbers from the * user and displays some statistics about the numbers. */
Function Header Comments
EACH FUNCTION must have a header comment that includes the following:
- a description of what the function does
- a description of the function's inputs (if there are inputs)
- a description of the function's outputs (if there are outputs)
- side effect(s) of the function (if any — this should be rare)
/** * Calculate the area of a circle with the specified radius. * * @param[in] radius measured in inches * @return circle's area, measured in square inches */The astute reader will recognize this style as similar to Doxygen comments.
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) should be documented. A particularly
important line of code should also be commented.
Do not comment every line of code. Trivial
comments (such as // 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:
// Get from user a radius and convert it to radians fgets(input_buf, sizeof(input_buf), input_file); radius = degrees_to_radians(input_buf);
Comments for Variables
Add a comment when initializing variables, like in the examples below.
// total students in this section int num_students = 0; // final exam average float final_avg = 0.0;You do not have to comment every variable. If the name is descriptive enough, it is not necessary to comment. In the above example, a comment would not have been necessary if the variables had been named
num_students
and final_exam_average
.