-
All source files must be appropriately named, using lowercase;
often the class being defined or implemented will determine the name
of the source file. For example, for the Point class, the header file
will be named "point.h".
-
All source files must have a cleanly formatted header comment containing
the following information: filename, name of author, date of creation,
description of file. A header comment may look like this:
//////////////////////////////////////////////////////////
// Filename: foo.cpp
// Author: Richard Liston
// Date: Sun Jan 15 19:13:03 EST 2006
//
// Description: This file contains the implementation of
// functions to solve poverty and achieve
// world peace.
//
//////////////////////////////////////////////////////////
-
If you are modifying pre-existing code, continue modifying in the same
style as the existing code unless changing the style will significantly
increase the quality of the code. Make explicit notes about what was
modified:
//////////////////////////////////////////////////////////
// Filename: foo.cpp
// Author: Richard Liston
// Date: Sun Jan 15 19:13:03 EST 2006
//
// Description: This file contains the implementation of
// functions to solve poverty and achieve
// world peace.
//
// Modified: George Jetson, Thu Feb 7 11:20:25 EST 2008
// Added function to minimize cost.
//
//////////////////////////////////////////////////////////
-
One rule of thumb is for code to consist of roughly 50% comments.
Comments always go before the item being commented. NOTE: this differs from
the style used in the text.
-
Comments should not state the obvious:
// BAD: This function takes an int and returns a bool.
// GOOD: This function determines whether or not the argument is an
// even integer greater than zero.
-
Every structure, class, #define, and user-defined type requires a comment.
-
Always use a block for the body of a loop or conditional, even if there
is only one statement:
if (i == j)
{
return 0;
}
-
Every variable and object should have its own comment unless it is more
clear to group several under one comment (e.g., they all do the same thing).
-
Every function and method (member function) requires comments:
a brief description of the function, descriptions of the inputs and outputs,
and pre and postconditions go in the header file. A precondition may be
omitted if the function will work with any values for the inputs:
class Color
{
.
.
.
// Description: calculates the average value of three chars
// Post: Returns the average of the red, green and blue values as an
// unsigned char.
unsigned char Average(const Color&);
.
.
.
};
An overview of how the function operates goes before the function in the
implementation file:
// Converts the chars to integers so the total can take on a value above
// 255, adds them up and divide the result by three. Converts the result
// to an unsigned char before returning.
unsigned char Color::Average(const Color& c)
{
.
.
.
};
-
Global variables should only be used when they are absolutely
unavoidable (like when programming in OpenGL). If they are used a
comment should describe why they are unavoidable.
-
Fail early and give useful information for the user. For example,
after opening a file check to make sure the file successfully opened.
If not, tell the user about it:
inFile.open(filename.c_str());
if (!inFile)
{
cout << "ERROR: Unable to open " << filename << " ...exiting." << endl;
exit(1);
}
-
All inputs should be tested for sanity. If the values of the inputs are
not valid, handle the error. Some possibilities for handling errors are:
Use assert(); print an error and exit; or return a value that indicates
the existence of the error. For example:
inFile >> numIntegers;
if (!inFile)
{
cout << "ERROR: bad file format" << endl;
cout << "Unable to read number of integers from "
<< filename << " ...exiting." << endl;
exit(1);
}
-
Error messages in programs should have the form
ERROR: Unable to ...
Where necessary, state which input file caused the error.
-
Loops require comments about what the loop does and how it operates.
-
All important or non-obvious lines of code must be commented.
-
Each function should perform a concise, well-defined task. Functions
that are too complex should be broken up into multiple functions. One
rule of thumb states that functions to be no longer than about 60 lines.
-
All identifiers (variable names, function names, etc.) must be
meaningful and descriptive. Note that C and C++ follow different
naming conventions for their identifiers. In C identifiers are typically
lowercase, with "words" separated by underscores. In C++ words are usually
run together with each word capitalized, except that variables begin with
lowercase letters:
double distanceInMeters;
-
Indent blocks of code inside braces by 4 spaces (not tabbed, as is
recommended in some guidelines). Most editors can be configured to do
this automatically when it is editing C++ source code.
-
Lines must not exceed 79 spaces. Find reasonable ways to break lines.
This is so that code can be readably printed in two columns in landscape
mode on a single sheet of paper.
-
Matching braces must appear in the same column as shown:
infile >> size;
while (!infile)
{
if (size > MAX_SIZE)
{
cout << "Found a size greater than " << MAX_SIZE << endl;
}
infile >> size;
}
-
The code should not contain literal constants. Instead, define constants
for readability:
// Maximum intensity value for each pixel component
#define MAX_INTENSITY 255
These identifiers must be in all caps.
-
Use macro guards for all header files:
#ifndef POINT_H
#define POINT_H
...
#endif
This ensures that each header file will not be included more than once.
-
Each Makefile must have a "clean" rule that removes unnecessary
files: object (.o) files, output files that result from testing
the software, backup files left by editors, etc.
-
Code must be compiled with all warnings turned on, and it must
compile without any warnings.
-
A set of source files should be accompanied by a README file: a text
file describing issues related to the software:
- what each of the source files are
- what the software does
- how to compile and/or install the package
- anything else a user of the software may need to know
If the README becomes too long it can be split up into other files
(like a README.install or just and INSTALL file), but this usually
won't be the case for course work.