|
Employing good and consistent coding conventions is very important: it helps make the programs
more readable, improves productivity, and enhances group collaboration. For these reasons,
the following standards are given as guidelines to follow (others
feel more strongly about the issue). Additionally, more readable code
requires fewer comments to be understood! The most important
thing about coding conventions is that you remain consistent and stick
to a convention within a single program.
Names
All identifiers should be meaningful to make your code easier to understand.
The identifiers x and y are meaningful as coordinates,
but not for much else (ok, maybe chromosomes too). It is fine to use single
letter identifiers for loop control variables, e.g., j and k.
Variable identifiers should begin with lower-case letters. Capital letters
are used, rather than underscores, to differentiate long names.
Using the following naming conventions will keep code ambiguities to
a minimum.
| Classes |
Examples: Dice or SlinkyDog |
Classes should be named using nouns which describe what the class models.
Although most standard C++ class names begin with a lowercase letter, your
class names should begin with a capital letter. This helps distinguish
between classes you create and those standard to C++. Classes should be
documented with their purpose in the program as well as the invariants required
of their state to ensure the object behaves correctly.
| Method Names |
Examples: roll() or fly() |
Methods usually perform some kind of action and/or return a value, so use verbs to indicate what they do.
Unlike class names, method names
should start with a lowercase letter as do standard C++ method
names. Methods should be documented with the pre - and post-conditions that form
a contract for when the method behaves properly (i.e., if the pre-condition is true when the function
is called, the post-condition will be satisfied when the function finishes).
| Accessor Methods |
Example: getLocation() or getToyOwner() |
Accessors that retrieve the value
of an instance are named after the the variable they are going to retrieve
and prefixed with the word "get". These functions should be made
const. You should try to limit the number
of these functions you write.
| Mutator Methods |
Example: setToyOwner(const string& ownerName) |
Mutators that change the value of one or more instance variables are named after the variable
being changed and prefixed with the
word "set". Most of
the time mutators take the new value of the variable they are changing
as a parameter. You should try to limit the number of these functions
you write.
| Instance and Local Variables |
Examples: myNumGreenArmyMen and numToys |
Instance and local variables store the state of the object.
Their names should be comprised of nouns describing the information they
store. All instance and local variable names begin with a lowercase letter. In addition, all instance
variables should be prefaced by the word my. Static class
variables should begin with the prefix our indicating the per-class
nature of the variable. This allows you to easily differentiate between
instance and local variables, which is very handy.
| Constants |
Example: MAX_STUDENTS or SIDS_IQ |
Constants should be nouns describing their content. In order
to distinguish them from just plain variables, use only capital letters
in their names.
| Parameters |
Example: goto(const string& who, const Point& where) |
Parameters should be passed by const ref unless you have a strong compelling
reason to do otherwise, in which case those reasons should be commented.
Indentation and Skipping Lines
C++ consists of nested blocks of code. For example if statements
can be contained in for loops, which are contained in methods.
One way to show this nesting is by indentation. This allows the person
reading your code to easily see the major sections of code and main flow-of-control
in methods.
-
Nested code should be indented
-
Indentation conventions should use as much white space as necessary to
make it clear what is going on.
char ch;
while (input.get(ch))
counts[tolower(ch)]++;
Braces
Braces indicate the beginning and end of blocks of code. Class definitions,
methods, and loops all have braces around them. The opening brace should
be on the next line after the beginning of the block; i.e., if the braces
are around the class, the opening brace is on the line after the name of
the class; if the braces are around the method, the opening brace is on
the line after the name of the method etc. The closing brace should be
aligned with the beginning of the line with the opening brace. Note, this automatically creates
an essentially blank line between the top of your block and its contents,
making your code more readable.
char ch;
while (input.get(ch))
{
if (isalpha(ch))
{
total++;
}
ch = tolower(ch);
counts[ch]++;
}
Skipping Lines
Another way of making major sections of your code easy to see is by skipping
lines. You should skip about two lines between methods. You should also
separate
logical chunks of code within a method with one or two blank lines.
Documentation
No matter how simple a program is to its author, it is almost always confusing
to another person reading it. Comments are used for adding information to your code by describing
the purpose of the code. Your comments should not just repeat the code
that you have written, as such comments are useless. Comments should be
added whenever an explanation or clarification is needed for some section
or line of code, such as a difficult sequence of commands, an unusual
or atypical design pattern, or a very brief synopsis of what a particular
method call might do or return.
We suggest you comment as you go
along. Do not leave all your commenting until the end of the project.
Commenting done later takes more time because you have to remember or figure
out what the code is doing instead of just writing down what you are already
thinking about.
| time++; // add one to time |
<- useless |
| time++; // update clock to current hour |
<- useful |
To generate program documentation, you can use a variation on C++'s multi-line comment that starts with
/**
and ends in the standard */. Several programs, including DOC++,
can process these special documentation comments to automatically generate HTML documentation for your code based on comments
written directly within the code.
|
