Programming style is the one thing which varies the most from programmer to programmer. However, working in a group environment requires that each member of the group stick to common coding practices. Our goal is that each member of our group write code which is stylistically indistinguishable from the other members' code. This is particularly important in a university environment since code is often passed from generation to generation of students in our group. So in the ISIP style guide we try to remove as much "creative" freedom as possible from the programmer and, in doing so, provide consistency for our sponsors.
Listed below are points which should guide the programmer in writing code to fit the ISIP Standard.
- General style issues
- Comments
- Naming conventions
- Operations
- Loop structures and branch statements
- Method and function types
- Default arguments
Return to C++ Programming Standards Page
General style issues
-
One should avoid lines of code greater than 79 characters long.
This allows one to easily print the code and to view it in
a normal-sized window.
-
Spacing and tabification is strictly dictated by Emacs c++-mode.
-
Each method file can contain only a single method and said
method should occupy roughly one screen (40 lines). If your
function is much longer than one screen, then you may want to
consider splitting it into two or more separate functions. Of
course, in some cases this cannot be avoided.
The exception to this rule is when two functions of the same name where the only difference is default arguments: one of the methods calls the other method with only a trivial amount of setup. In this case, the trivial method should precede the full method in the file. Each method is still required to have a full method comment.
One example of having two methods in the same file is found in the SysString class. To provide a more useful interface, most of the member functions can accept either SysString objects or pointers to unichar strings. All of the methods are implemented with SysStrings, though, so we need an easy way to provide this functionality. We do this by making all versions of the methods which accept unichar* arguments simply create a SysString object and then call the master function. The SysString::concat() method is an example of this:
Another example is with default arguments.// method: concat // // arguments: // unichar* buf: (input) buffer of characters to concatenate // // return: logical error status // // concatenate buf to current object // boolean SysString::concat(unichar* buf_a) { // create a temporary string object // SysString temp(buf_a); // call the master function // return concat(temp); } // method: concat // // arguments: // SysString&abs str: (input) string to concatenate // // return: logical error status // // concatenate str to current object // boolean SysString::concat(SysString& str_a) { ... }
-
Comment liberally even in header files. A general rule is that
every 3-5 lines of code should be accompanied by comments.
However, commenting trivial operations such as incrementing
of index variables is not necessary.
-
Ample debugging information should be provided through the use
of the Integral::DEBUG_* constants defined in
Integral.h
Note that when printing debug output, you should use Console.// provide debugging information // if (debug_level_d == Integral::DEBUG_FULL) { SysString output; output.assign(L"
-
Do not call any function not defined in ISIP software. This
includes stdio.h, stdlib, math.h, or any other operating
system-provided libraries. Wrappers for useful functions are
provided in the Integral class for common math functions, but
for the most part these functions can be avoided by using the
appropriate class member functions. For example, strcmp()
exists as SysString::compare(), log() exists as
Double::log(), and fprintf(stdout, ...) exists as
Console::put().
-
Use constants defined in header files rather than explicit
values whenever possible. For instance:
should be replaced byif (option_a.eq(L"-sf")) {
where OPT_SF was defined in the constants section of the class header:if (option_a.eq((unichar*)OPT_SF)) {static const unichar OPT_SF[] = L"-sf"; -
The open brace should always appear at the end of the line with a
space between it and the preceding code. The closing brace should
always appear on a line by itself (except possibly comments).
if (flag) { // exit gracefully // flag = ISIP_FALSE; }
-
The last line in a comment-block should be a blank comment
line.
-
Lines of code should come after the comment block without
blank lines in between.
-
The first line in a comment block should be preceded by a blank
line.
-
All characters in comment lines should be lower-case.
- Here is an example of a valid comment
// provide debugging information // if (debug_level_d == ISIP_DEBUG_FULL) { fprintf(stdout, "
Constant names: Constant names follow the same rules as variable names with a few additional constraints.
-
All letters in constant names are capitalized.
-
All constant names are multi-word with each word being
separated by an underscore.
-
The first word in constant names is an abbreviation for
the class or program for which the constants were
defined.
-
There is no distinction made between class constants or
any other type of constant (i.e. the "_d" is
not necessary.)
-
Only constants defined in integral_constants.h
should be prefaced by ISIP.
-
Examples of valid constant names
// constant for the sof class // #define SOF_CLASS_NAME (char_1*)"Sof" // constants for the fourier transform class // #define FT_FH_NAME (char_1*)"fh" #define FT_DEFAULT_ORDER (int_4)"1024"
-
The first letter in the class name is capitalized. This is
the only letter in the name which is capitalized even if
the class name is a multi-word.
-
Class names should accurately describe the object they are
defining.
-
The first three of the following class declarations are
incorrect. They are followed by the preferred form.
// this one has a lower-case letter for the first character // class fourier_transform { // this one is not multi-word and uses an upper-case // in an improper location // class FourierTransform { // this one is not descriptive enough // class Fourier { // this one follows all of the rules for naming classes // class Fourier_transform {
verb_noun
-
The verb portion of this program name indicates what type
of action(s) is performed.
-
The noun portion of this program name indicates the type
of data that the action is performed upon.
-
Below are two examples of incorrect program names and their
corrected form
fft_analysis // not preferred: not in verb_noun form analyze_fft // preferred find // not preferred: noun portion is missing find_noun_form // preferred
-
Names must describe what task the function performs.
-
Names must have all lower-case letters.
-
Words in multi-word names are separated by underscores.
-
All names are suffixed by "_cc".
-
Some examples of function names follow
// this method sets the delimiter character used in an ascii sof file // logical_1 Sof::set_delimiter_cc(char_1 value_a) { // this method replaces all environment variables and other such // things in a string with their equivalent expansions. // logical_1 Sof::expand_cc(char_1* o_name_a, char_1* i_name_a) { // this function gets the command-line parameters for a utility // logical_1 get_params_cc(int argc_a, char** argv_a, int_4& mode_a, int_4& dbg_level_a) {
Mathematical and boolean operations:
-
All mathematical operations and comparisons should
follow the form:
for example<left_operand> <operator> <right_operand>int_4 i = (int_4)1; int_4 j = (int_4)2; float_4 k = (float_4)0.0; i = i * y; k = (float_4)(j * i); i = (int_4)((float_4)j + k); for (int_4 i = 0; i < length; i++) { -
All operators should be bordered by a single space on
both sides.
// an example. // if (name<=SENT_NAME) { // not preferred if (name<= SENT_NAME) { // not preferred if (name <=SENT_NAME) { // not preferred if (name <= SENT_NAME) { // not preferred if (name <= SENT_NAME) { // preferred
-
Parentheses should be used as needed to override
precedence or for clarity. When in doubt, it is better
to have too many parentheses than too few.
-
Use casting to explicitly set types at all times.
-
If possible, do not split comparisons across lines.
-
When performing compound boolean operations, always
use parentheses to separate the different comparisons.
This provides much greater clarity in your code as well
as making it easier to debug.
if (((i < k) && (j == 10)) || (k >= j)) { -
Boolean tests should not explicitely compare against
Integral::TRUE and Integral::FALSE. For instance,
should be replaced byif (flag == Integral::TRUE) { // exit gracefully // flag = ISIP_FALSE; }
Also, most functions which return boolean return a logical error status. This means that if they operate correctly, they will return Integral::TRUE, else Integral::FALSE. To wrap a method for error handling you should useif (flag) { // exit gracefully // flag = ISIP_FALSE; }
rather thanif (!processData(data)) { return Error::handle(name(), L"method-name", ERR_PROCESS); }if (processData(data) != Integral::TRUE) { return Error::handle(name(), L"method-name", ERR_PROCESS); } -
It is not acceptable to use a non boolean value for a logical
expression. While C++ allows that the value 0 is false and all
other values are true, this is not good programming practice. If you want to branch on a numeric value, explicitely state this in a logical expression, i.e. while (i != 0).
Use of quotes should be reserved for header files which reside in the same directory as the one doing the include. All others should use angle brackets.#include <integral.h> #include "fourier_transform.h"
Loop structures and branch statements
-
switch statement:
The switch statement,
is generally to be avoided due to its complexity and the
ambiguity which can easily occur. In its place we use the
if-else constructs.
- if-else statement: The if-else statement follows the following form - particularly note the spacing.
Of course, the else if and/or else statements can be left off if necessary. Note that nested if statements require no special form.if (<comparison_1>) { // operations // } else if (<comparison_2>) { // operations // } <...optionally more "else if" statements...> else { // operations // }
Although it is not strictly against the standard to have if statements of the following form, it is generally better to explicitly put the opening and closing brackets as it clearly indicates what is in the if statement and it allows one to easily add operations to the if block at a later date.
An example of an if statement is shown here:if (<comparison>) <operation>;if (flag == ISIP_TRUE) { // assign a default value to the length // length = CLASS_DEFAULT_LENGTH; // check for the bounds on the length. if the length // is within the upper-bound return true else false // if (length <= CLASS_UPPER_BOUND) { // exit gracefully // return ISIP_TRUE; } else { // exit gracefully // return ISIP_FALSE; } } else { // exit gracefully // return ISIP_TRUE; }- for loop: The for loop conventions are not much different than the if statement. A typical for loop is shown below.
Notice that there is a space after each semi-colon in the for-loop declaration.// loop over all characters in the array // for (int_4 i = (int_4)0; i < ISIP_MAX_STRING_LENGTH; i++) { // print the character at this location // fprintf(stdout, "%c\n", (char)buffer_a[i]); }
- while loop: The while loop follows the same conventions as the if statement. An example follows
The standard procedure for creating indefinite loops is also with the while loop.int_4 i = 0; while (i < CLASS_MAX_SIZE) { // increment i by a predefined amount // i += CLASS_INCR_SIZE; }while (1) { // conditions which eventually lead to a break condition // }- do loop: The do loop follows the conventions of the if loop for spacing, etc.
int_4 i = 0; do { // increment i by a predefined amount // i += CLASS_INCR_SIZE; } while (i < CLASS_MAX_SIZE); - if-else statement: The if-else statement follows the following form - particularly note the spacing.
// return: a logical_1 value indicating status
//
// this method sets the delimiter character used in an ascii sof file
//
logical_1 Sof::set_delimiter_cc(char_1 value_a) {
delimiter_d = value_a;
// exit gracefully
//
return ISIP_TRUE;
}
Of course, functions or methods can also return any type of data. Some
examples of various methods are shown below.
// return: the last dtmf key hit on this channel (if not cleared)
//
char_1 Channel::get_last_dtmf_cc() {
// exit gracefully
//
return dtmf_d;
}
// return: the last dtmf key hit on this channel (if not cleared)
//
VCB* Channel::get_vcb_cc() {
// exit gracefully
//
return &vcb_d;
}
Default Arguments:
If the
default argument is an integral type, use the standard C++ notation
for default arguments, specifically
// assignment method
//
boolean assign(byte* data, long encoding = SysChar::DEF_ENCODE);
Notice that this effectively creates two versions of the assign method,
// assignment method
//
boolean assign(byte* data, long encoding);
boolean assign(byte* data) {
return assign(data, SysChar::DEF_ENCODE);
}
The problem arises when the argument you wish to make default
is a class, this framework does not work. The solution is to
put both methods in the same method file. The
