C++ Programming Style Guidelines for OpenMD-1.0

Version 1.0, September 2004

OpenMD Developement Team

Department of Chemistry & Biochemistry

University of Notre Dame

Notre Dame, IN 46556

The original document is available at http://geosoft.no/development/cppstyle.html

Table of Content

1 Introduction

4 Files

5 Statements

6 Layout and White Space

7 Comments and Documentation

8 References

1 Introduction

This document lists C++ coding recommendations common in the C++ development community.

The recommendations are based on established standards collected from a number of sources, individual experience, local requirements/needs, as well as suggestions given in [1] - [4].

There are several reasons for introducing a new guideline rather than just referring to the ones above. Main reason is that these guides are far too general in their scope and that more specific rules (especially naming rules) need to be established. Also, the present guide has an annotated form that makes it far easier to use during project code reviews than most other existing guidelines. In addition, programming recommendations generally tend to mix style issues with language technical issues in a somewhat confusing manner. The present document does not contain any C++ technical recommendations at all, but focuses mainly on programming style. For guidelines on C++ programming style refer to the C++ Programming Practice Guidelines.

While a given development environment (IDE) can improve the readability of code by access visibility, color coding, automatic formatting and so on, the programmer should never rely on such features. Source code should always be considered larger than the IDE it is developed within and should be written in a way that maximize its readability independent of any IDE.

1.1 Layout of the Recommendations.

The recommendations are grouped by topic and each recommendation is numbered to make it easier to refer to during reviews.

Layout of the recommendations is as follows:

Guideline short description
`Good example if applicable`	`Bad example if applicable`
Motivation, background and additional information.

The motivation section is important. Coding standards and guidelines tend to start "religious wars", and it is important to state the background for the recommendation.

1.2 Recommendation Importance

In the guideline sections the terms must, should and can have special meaning. A must requirement must be followed, a should is a strong recommendation, and a can is a general guideline.

2 General Recommendations

1. Any violation to the guide is allowed if it enhances readability.

The main goal of the recommendation is to improve readability and thereby the understanding and the maintainability and general quality of the code. It is impossible to cover all the specific cases in a general guide and the programmer should be flexible.

2. The rules can be violated if there are strong personal objections against them.

The attempt is to make a guideline, not to force a particular coding style onto individuals. Experienced programmers normally want adopt a style like this anyway, but having one, and at least requiring everyone to get familiar with it, usually makes people start thinking about programming style and evaluate their own habits in this area.

On the other hand, new and inexperienced programmers normally use a style guide as a convenience of getting into the programming jargon more easily.

3 Naming Conventions

3.1 General Naming Conventions

3. Names representing types must be in mixed case starting with upper case.

Line, SavingsAccount

Common practice in the C++ development community.

4. Variable names must be in mixed case starting with lower case.

line, savingsAccount

Common practice in the C++ development community. Makes variables easy to distinguish from types, and effectively resolves potential naming collision as in the declaration Line line;

5. Named constants (including enumeration values) must be all uppercase using underscore to separate words.

MAX_ITERATIONS, COLOR_RED, PI

Common practice in the C++ development community. In general, the use of such constants should be minimized. In many cases implementing the value as a method is a better choice:

int getMaxIterations() // NOT: MAX_ITERATIONS = 25
{
return 25;
}

This form is both easier to read, and it ensures a unified interface towards class values.

6. Names representing methods or functions must be verbs and written in mixed case starting with lower case.

getName(), computeTotalWidth()

Common practice in the C++ development community. This is identical to variable names, but functions in C++ are already distingushable from variables by their specific form.

7. Names representing namespaces should be all lowercase.

analyzer, iomanager, mainwindow

Common practice in the C++ development community.

8. Names representing template types should be a single uppercase letter.

template<typename T> ...
template<typename C, typename D> ...

Common practice in the C++ development community. This makes template names stand out relative to all other names used.

9. Abbreviations and acronyms must not be uppercase when used as name [4].
`exportHtmlSource();` `openDvdPlayer();`	`exportHTMLSource();` `openDVDPlayer();`
Using all uppercase for the base name will give conflicts with the naming conventions given above. A variable of this type whould have to be named dVD, hTML etc. which obviously is not very readable. Another problem is illustrated in the examples above; When the name is connected to another, the readbility is seriously reduced; the word following the abbreviation does not stand out as it should.

10. Global variables should always be referred to using the :: operator.

::mainWindow.open(), ::applicationContext.getName()

In general, the use of global variables should be avoided. Consider using singleton objects instead.

11. Private class variables should have underscore suffix.

class SomeClass {
private:
int length_;
}

Apart from its name and its type, the scope of a variable is its most important feature. Indicating class scope by using underscore makes it easy to distinguish class variables from local scratch variables. This is important because class variables are considered to have higher significance than method variables, and should be treated with special care by the programmer.

A side effect of the underscore naming convention is that it nicely resolves the problem of finding reasonable variable names for setter methods and constructors:

void setDepth (int depth)
{
depth_ = depth;
}

An issue is whether the underscore should be added as a prefix or as a suffix. Both practices are commonly used, but the latter is recommended because it seem to best preserve the readability of the name.

It should be noted that scope identification in variables has been a controversial issue for quite some time. It seems, though, that this practice now is gaining acceptance and that it is becoming more and more common as a convention in the professional development community.

12. Generic variables should have the same name as their type.

void setTopic (Topic *topic)

void connect (Database *database)

void setTopic (Topic *value)
void setTopic (Topic *aTopic)
void setTopic (Topic *x)

void connect (Database *db)
void connect (Database *oracleDB)

Reduce complexity by reducing the number of terms and names used. Also makes it easy to deduce the type given a variable name only.

If for some reason this convention doesn't seem to fit it is a strong indication that the type name is badly chosen.

Non-generic variables have a role. These variables can often be named by combining role and type:

Point startingPoint, centerPoint;
Name loginName;

13. Variables with a large scope should have long names, variables with a small scope can have short names [1].

Scratch variables used for temporary storage or indices are best kept short. A programmer reading such variables should be able to assume that its value is not used outside a few lines of code. Common scratch variables for integers are i, j, k, m, n and for characters c and d.

14. The name of the object is implicit, and should be avoided in a method name.

line.getLength(); // NOT: line.getLineLength();

The latter seems natural in the class declaration, but proves superfluous in use, as shown in the example.

3.2 Specific Naming Conventions

15. The terms get/set must be used where an attribute is accessed directly.

employee.getName(); matrix.getElement (2, 4);
employee.setName (name); matrix.setElement (2, 4, value);

Common practice in the C++ development community. In Java this convention has become more or less standard.

16. The term compute can be used in methods where something is computed.

valueSet->computeAverage(); matrix->computeInverse()

Give the reader the immediate clue that this is a potential time consuming operation, and if used repeatedly, he might consider caching the result. Consistent use of the term enhances readability.

17. The term find can be used in methods where something is looked up.

vertex.findNearestVertex(); matrix.findMinElement();

Give the reader the immediate clue that this is a simple look up method with a minimum of computations involved. Consistent use of the term enhances readability.

18. The term initialize can be used where an object or a concept is established.

printer.initializeFontSet();

The american initialize should be preferred over the english initialise. Abbreviation init should be avoided.

19. Variables representing GUI components should be suffixed by the component type name.

mainWindow, propertiesDialog, widthScale, loginText, leftScrollbar, mainForm, fileMenu, minLabel, exitButton, yesToggle etc.

Enhances readability since the name gives the user an immediate clue of the type of the variable and thereby the objects resources.

20. The suffix List can be used on names representing a list of objects.

vertex (one vertex), vertexList(a list of vertices)

Enhances readability since the name gives the user an immediate clue of the type of the variable and the operations that can be performed on the object.

Simply using the plural form of the base class name for a list (matrixElement (one matrix element), matrixElements (list of matrix elements)) shoul be avoided since the two only differ in a single character and are thereby difficult to distinguish.

A list in this context is the compound data type that can be traversed backwards, forwards, etc. (typically an STL vector). A plain array is simpler. The suffix Array can be used to denote an array of objects.

21. The prefix n should be used for variables representing a number of objects.

nPoints, nLines

The notation is taken from mathematics where it is an established convention for indicating a number of objects.

22.The suffix No should be used for variables representing an entity number.

tableNo, employeeNo

The notation is taken from mathematics where it is an established convention for indicating an entity number.

An elegant alternative is to prefix such variables with an i: iTable, iEmployee. This effectively makes them named iterators.

23. Iterator variables should be called i, j, k etc.

for (int i = 0; i < nTables); i++) {
:
}

vector<MyClass>::iterator i;
for (i = list.begin(); i != list.end(); i++) {
Element element = *i;
...
}

The notation is taken from mathematics where it is an established convention for indicating iterators.

24. The prefix is should be used for boolean variables and methods.

isSet, isVisible, isFinished, isFound, isOpen

Common practice in the C++ development community and partially enforced in Java.

Using the is prefix solves a common problem of choosing bad boolean names like status or flag. isStatus or isFlag simply doesn't fit, and the programmer is forced to choose more meaningful names.

There are a few alternatives to the is prefix that fits better in some situations. These are the has, can and should prefixes:

bool hasLicense();
bool canEvaluate();
bool shouldSort();

25. Complement names must be used for complement operations [1].

get/set, add/remove, create/destroy, start/stop, insert/delete, increment/decrement, old/new, begin/end, first/last, up/down, min/max, next/previous, old/new, open/close, show/hide, suspend/resume, etc.

Reduce complexity by symmetry.

26. Abbreviations in names should be avoided.

computeAverage();

compAvg();

There are two types of words to consider. First are the common words listed in a language dictionary. These must never be abbreviated. Never write:

cmd   instead of command
cp    instead of copy
pt    instead of point
comp instead of compute
init instead of initialize
etc.

Then there are domain specific phrases that are more naturally known through their abbreviations/acronym. These phrases should be kept abbreviated. Never write:

HypertextMarkupLanguage instead of html
CentralProcessingUnit instead of cpu
PriceEarningRatio instead of pe
etc.

27. Naming pointers specifically should be avoided.

Line *line;

Line *pLine;

Line *linePtr

Many variables in a C/C++ environment are pointers, so a convention like this is almost impossible to follow. Also objects in C++ are often oblique types where the specific implementation should be ignored by the programmer. Only when the actual type of an object is of special significance, the name should empahsize the type.

28. Negated boolean variable names must be avoided.

bool isError;
bool isFound;

bool isNoError

bool isNotFound

The problem arises when such a name is used in conjunction with the logical negation operator as this results in a double negative. It is not immediately apparent what !isNotFound means.

29. Enumeration constants can be prefixed by a common type name.

enum Color {
     COLOR_RED,
     COLOR_GREEN,
     COLOR_BLUE
};

This gives additional information of where the declaration can be found, which constants belongs together, and what concept the constants represent.

An alternative approach is to always refer to the constants through their common type: Color::RED, Airline::AIR_FRANCE etc.

30. Exception classes should be suffixed with Exception.

class AccessException {
:
}

Exception classes are really not part of the main design of the program, and naming them like this makes them stand out relative to the other classes.

31. Functions (methods returning something) should be named after what they return and procedures (void methods) after what they do.

Increase readability. Makes it clear what the unit should do and especially all the things it is not supposed to do. This again makes it easier to keep the code clean of side effects.

4 Files

4.1 Source Files

32. C++ header files should have the extension .hpp. Source files can have the extension .cpp (recommend), .cc, .c++ or .C. And all of the file names shold be capitalized.

MyClass.hpp

MyClass.cpp

myClass.hpp

myClass.cpp

These are all accepted C++ standards for file extension.

33. A class should be declared in a header file and defined in a source file where the name of the files match the name of the class.

MyClass.hpp, MyClass.cpp

Makes it easy to find the associated files of a given class. This convention is enforced in Java and has become very successful as such.

34. All definitions should reside in source files.

class MyClass
{
public:
int getValue () {return value_;} // NO!
...
private:
int value_;
}

The header files should declare an interface, the source file should implement it. When looking for an implementation, the programmer should always know that it is found in the source file. The obvious exception to this rule is of course inline functions that must be defined in the header file.

35. File content must be kept within 80 columns.

80 columns is a common dimension for editors, terminal emulators, printers and debuggers, and files that are shared between several people should keep within these constraints. It improves readability when unintentional line breaks are avoided when passing a file between programmers.

36. Special characters like TAB and page break must be avoided.

These characters are bound to cause problem for editors, printers, terminal emulators or debuggers when used in a multi-programmer, multi-platform environment. Xemacs inserts hard TAB into files which should be avoided

Indent everything to 4 spaces

37. The incompleteness of split lines must be made obvious [1].

totalSum = a + b + c +
           d + e;
function (param1, param2,
          param3);
setText ("Long line split"
         "into two parts.");
for (tableNo = 0; tableNo < nTables;
     tableNo += tableStep)

Split lines occurs when a statement exceed the 80 column limit given above. It is difficult to give rigid rules for how lines should be split, but the examples above should give a general hint.

In general:

Break after a comma.
Break after an operator.
Align the new line with the beginning of the expression on the previous line.

4.2 Include Files and Include Statements

38. Header files must include a construction that prevents multiple inclusion. The convention is an all uppercase construction of the module name, the file name and the hpp suffix.
`#ifndef MOD_FILENAME_H`PP `#define MOD_FILENAME_H`PP `:` `#endif`	`#ifndef _MOD_FILENAME_H`PP_ `#define _MOD_FILENAME_H`PP_ `:` `#endif`
The construction is to avoid compilation errors. The name convention is common practice. The construction should appear in the top of the file (before the file header) so file parsing is aborted immediately and compilation time is reduced.

39. Include statements should be sorted and grouped. Sorted by their hierarchical position in the system with low level files included first. Leave an empty line between groups of include statements.

#include <fstream>
#include <iomanip>

#include <Xm/Xm.h>
#include <Xm/ToggleB.h>

#include "ui/PropertiesDialog.h"
#include "ui/MainWindow.h"

In addition to show the reader the individual include files, it also give an immediate clue about the modules that are involved.

Include file paths must never be absolute. Compiler directives should instead be used to indicate root directories for includes.

40. Include statements must be located at the top of a file only.

Common practice. Avoid unwanted compilation side effects by "hidden" include statements deep into a source file.

5 Statements

5.1 Types

41. Types that are local to one file only can be declared inside that file.

Enforces information hiding.

42. The parts of a class must be sorted public, protected and private [2][3]. All sections must be identified explicitly. Not applicable sections should be left out.

The ordering is "most public first" so people who only wish to use the class can stop reading when they reach the protected/private sections.

43. Type conversions must always be done explicitly. Never rely on implicit type conversion.
`floatValue` `= static_cast<float> (intValue); // YES!`	`floatValue` `= intValue; // NO!`
By this, the programmer indicates that he is aware of the different types involved and that the mix is intentional.

5.2 Variables

44. Variables should be initialized where they are declared.

int x = 10;

int y = 20;

int x;

int y;

x = 10;

y = 20;

This ensures that variables are valid at any time. Sometimes it is impossible to initialize a variable to a valid value where it is declared:

int x, y, z;
getCenter (&x, &y, &z);

In these cases it should be left uninitialized rather than initialized to some phony value.

45. Variables must never have dual meaning.

Enhance readability by ensuring all concepts are represented uniquely. Reduce chance of error by side effects.

46. Use of global variables should be minimized.

In C++ there is no reason global variables need to be used at all. The same is true for global functions or file scope (static) variables.

47. Class variables should never be declared public.

The concept of C++ information hiding and encapsulation is violated by public variables. Use private variables and access functions instead. One exception to this rule is when the class is essentially a data structure, with no behavior (equivalent to a C struct). In this case it is appropriate to make the class' instance variables public [2].

Note that structs are kept in C++ for compatibility with C only, and avoiding them increases the readability of the code by reducing the number of constructs used. Use a class instead.

48. Related variables of the same type can be declared in a common statement [3].
Unrelated variables should not be declared in the same statement.

float x, y, z;
float revenueJanuary, revenueFebruary, revenueMarch;

The common requirement of having declarations on separate lines is not useful in the situations like the ones above. It enhances readability to group variables like this.

49. C++ pointers and references should have their reference symbol next to the variable namerather than to the type name[3].
`float *x;` `int &y;`	`float* x;` `int& y`;
It is debatable whether a pointer is a variable of a pointer type (float* x) or a pointer to a given type (float x). Important in the recommendation given though is the fact that it is impossible to declare more than one pointer in a given statement using the first approach. I.e. float x, y, z; is equivalent with float *x; float y; float z; The same goes for references.

50. The `const` keyword should be listed before the type name.
`void f1 (const Widget *v);`	`void f1 (Widget const *v);`
Neither is better nor worse, but since the former is more commonly used that should be the convention.

51. Implicit test for 0 should not be used other than for boolean variables.

if (nLines != 0)
if (value != 0.0)

if (pointer != NULL)

if (!isBool)

if (nLines)
if (value)

if (!pointer)

if (isBool != false)

It is not necessarily defined by the compiler that ints and floats 0 are implemented as binary 0. Also, by using explicit test the statement give immediate clue of the type being tested. It is common also to suggest that pointers shouldn't test implicit for 0 either, i.e. if (line == 0) instead of if (line). The latter is regarded as such a common practice in C/C++ however that it can be used.

52. Variables should be declared in the smallest scope possible.

Keeping the operations on a variable within a small scope, it is easier to control the effects and side effects of the variable.

5.3 Loops

53. Only loop control statements must be included in the `for()` construction.
`sum = 0;` `for (i = 0; i < 100; i++)` `sum += value[i];`	`for (i = 0; sum = 0; i < 100; i++)` `sum += value[i];`
Increase maintainability and readability. Make it crystal clear what controls the loop and what the loop contains.

54. Loop variables should be initialized immediately before the loop.
`isDone = false;` `while (!isDone) {` `:` `}`	`bool isDone = false;` `:` `while (!isDone) {` `:` `}`

55. do-while loops can be avoided.

do-while loops are less readable than ordinary while loops and for loops since the conditional is at the bottom of the loop. The reader must scan the entire loop in order to understand the scope of the loop.

In addition, do-while loops are not needed. Any do-while loop can easily be rewritten into a while loop or a for loop. Reducing the number of constructs used enhance readbility.

56. The use of break and continue in loops should be avoided.

These constructs can be compared to goto and they should only be used if they prove to have higher readability than their structured counterpart.

57. The form `while(true)` should be used for infinite loops.
`while(true) {` `:` `}`	`for (;;) { // NO!` `:` `}` `while (1) { // NO!` `:` `}`
Testing against 1 is neither necessary nor meaningful. The form `for (;;)` is not very readable, and it is not apparent that this actually is an infinite loop.

5.4 Conditionals

58. The nominal case should be put in the if-part and the exception in the else-part of an if statement [1].

isError = readFile (fileName);
if (!isError) {
:
} else {
:
}

Makes sure that the exceptions don't obscure the normal path of execution. This is important for both the readability and performance.

59. The conditional should be put on a separate line.
`if (isDone)` `doCleanup();`	`if (isDone) doCleanup();`
This is for debugging purposes. When writing on a single line, it is not apparent whether the test is really true or not.

60. Executable statements in conditionals must be avoided.
`fileHandle = open (fileName, "w");` `if (!fileHandle) {` `:` `}`	`if` `(!(fileHandle = open (fileName, "w"))) {` `:` `}`
Conditionals with executable statements are just very difficult to read. This is especially true for programmers new to C/C++.

5.5 Template

61. typename instead of class should be used in template declaration

template <typename T>

inline const T& max (const T &a, const T &b);

template <class T>

inline const T& max (const T &a, const T &b);

Semantically there is no difference in this context. So, even if you use class here, any type may be used for template arguments. However, because this use of class can be misleading (not only class types can be substituted for T ). Thus, we prefer the use of typename in this context.

template <typename T, template<T*> class Buf>

class Structure;

If template declaration involves template template parameter, use class instead.

62. template keyword and its parameter must occupy at least one line

template<typename T>

somefunc(T);

template<typename T> somefunc(T);

5.6 Miscellaneous

63. The use of magic numbers in the code should be avoided. Numbers other than 0 and 1 should be considered declared as named constants instead.

If the number does not have an obvious meaning by itself, the readability is enhanced by introducing a named constant instead. A different approach is to introduce a method from which the constant can be accessed.

64. Floating point constants should always be written with decimal point and at least one decimal.

double total = 0.0; // NOT: double total = 0;
double speed = 3.0e8; // NOT: double speed = 3e8;

double sum;
:
sum = (a + b) * 10.0;

This empasize the different nature of integer and floating point numbers even if their values might happen to be the same in a specific case.

Also, as in the last example above, it emphasize the type of the assigned variable (sum) at a point in the code where this might not be evident.

65. Floating point constants should always be written with a digit before the decimal point.

double total = 0.5; // NOT: double total = .5;

The number and expression system in C++ is borrowed from mathematics and one should adhere to mathematical conventions for syntax wherever possible. Also, 0.5 is a lot more readable than .5; There is no way it can be mixed with the integer 5.

66. Functions must always have the return value explicitly listed.

int getValue() { // NOT: getValue()
:
}

If not exlicitly listed, C++ implies int return value for functions. A programmer must never rely on this feature, since this might be confusing for programmers not aware of this artifact.

67. goto should not be used.

Goto statements violates the idea of structured code. Only in some very few cases (for instance breaking out of deeply nested structures) should goto be considered, and only if the alternative structured counterpart is proven to be less readable.

68. "0" should be used instead of "NULL".

NULLis part of the standard C library, but is made obsolete in C++.

6 Layout and White Space

6.1 Layout

69. Basic indentation should be 4.

for (i = 0; i < nElements; i++)
a[i] = 0;

Indentation of 1 is to small to emphasize the logical layout of the code. Indentation larger than 4 makes deeply nested code difficult to read and increase the chance that the lines must be split. Choosing between indentation of 2, 3 and 4, 2 and 4 are the more common, we prefer 4.

70. Block layout should be as illustrated in example 1 below , and must not be as shown in example 2.

while (!done) {
doSomething();
done = moreToDo();
}

while (!done)
{
doSomething();
done = moreToDo();
}

Example 3 introduce an extra indentation level which doesn't emphasize the logical structure of the code as clearly as example 1 and 2.

71. The class declarations should have the following form:

classSomeClass : public BaseClass {
     public:
        ...
     protected:
         ...
     private:
         ...
}

This follows partly from the general block rule above. Must follow the order of these access keyword, public comes first, and then protected and private

72. The function declarations should have the following form:

void someMethod() {
...
}

This follows from the general block rule above.

73. The if-else class of statements should have the following form:

if (condition) {
     statements;
}

if (condition) {
     statements;
} else {
     statements;
}

if (condition) {
     statements;
} else if (condition) {
     statements;
} else {
     statements;
}

74. A for statement should have the following form:

for (initialization; condition; update) {
statements;
}

This follows from the general block rule above.

75. An empty for statement should have the following form:

for (initialization; condition; update)
;

This emphasize the fact that the for statement is empty and it makes it obvious for the reader that this is intentional. Empty loops should be avoided however.

76. A while statement should have the following form:

while (condition) {
statements;
}

This follows from the general block rule above.

77. A do-while statement should have the following form:

do {
statements;
} while (condition);

This follows from the general block rule above.

78. A switch statement should have the following form:

switch (condition) {
     case ABC :
        statements;
        break;

     default :
        statements;
        break;
}

Note that each case keyword is indented relative to the switch statement as a whole. This makes the entire switch statement stand out. Note also the extra space before the : character. The explicit Fallthrough comment should be included whenever there is a case statement without a break statement. Leaving the break out is a common error, and it must be made clear that it is intentional when it is not there.

79. A try-catch statement should have the following form:

try {
statements;
} catch (Exception &exception) {
statements;
}

This follows partly from the general block rule above. The discussion about closing brackets for if-else statements apply to the try-catch statments.

80. Single statement if-else, for or while statements can be written without brackets.

if (condition)
     statement;

while (condition)
     statement;

for (initialization; condition; update)
     statement;

It is a common recommendation (Sun Java recommendation included) that brackets should always be used in all these cases. However, brackets are in general a language construct that groups several statements. Brackets are per definition superfluous on a single statement.

81. The function return type can be put in the left column immediately above the function name.

void MyClass::myMethod () {
:
}

This makes it easier to spot function names within a file since one can assume that they all start in the first column.

6.2 White Space

82. - Conventional operators should be surrounded by a space character. - C++ reserved words should be followed by a white space. - Commas should be followed by a white space. - Colons should be surrounded by white space. - Semicolons in for statments should be followed by a space character.
`a = (b + c) * d;` `while (true) {` `doSomething (a, b, c, d);` `case 100 :` `for (i = 0; i < 10; i++) {`	`a=(b+c)*d` `while(true) ...` `doSomething (a,b,c,d);` `case 100:` `for (i=0;i<10;i++){`
Makes the individual components of the statements stand out. Enhances readability. It is difficult to give a complete list of the suggested use of whitespace in C++ code. The examples above however should give a general idea of the intentions.

83. Logical units within a block should be separated by one blank line.

Enhance readability by introducing white space between logical units of a block.

84. Variables in declarations should be left aligned.

AsciiFile *file;
int nPoints;
float x, y;

Enhance readability. The variables are easier to spot from the types by alignment.

7 Comments and Documentation

7.1 Comment

85. Use // for all comments, including multi-line comments.

// Comment spanning
// more than one line.

Since multilevel C-commenting is not supported, using // comments ensure that it is always possible to comment out entire sections of a file using /* */ for debugging purposes etc.

There should be a space between the "//" and the actual comment, and comments should always start with an upper case letter and end with a period.

86. Comments should be included relative to their position in the code. [1]
`while (true) {` `// Do something` `something();` `}`	`while (true) {` `// Do something` `something();` `}`
This is to avoid that the comments break the logical structure of the program.

7.2 Documentation

87. Documentation style should follow Doxygen conventions

Regarding standardized class and method documentation the Java development community is far more mature than the C++. This is of course becuase Java includes a tool for extracting such comments and produce high quality hypertext documentation from it.

There have never been a common convention for writing this kind of documentation in C++, so when choosing between inventing your own convention, and using an existing one, the latter option seem natural. As one of the most popular documentation tools for C++, Doxygen become our primary choice.

88. Documentation block style

/**

* … text …

*/

In Doxygen, there are several valid way to mark a documentation block, we prefer the java style

89. @ tag convention should be used

@author

\authour

Doxygen support two kinds of tag conventions which begin with “\” or “@”. Both of them are equivalent, however, we prefer the java style

One obviuos exception is using Latex to represent formula

90. File Documentation

/* * Copyright (C) 2000-2009 The Open Molecular Dynamics Engine (OpenMD) project * * Contact: gezelter@openscience.org * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public License * as published by the Free Software Foundation; either version 2.1 * of the License, or (at your option) any later version. * All we ask is that proper credit is given for our work, which includes * - but is not limited to - adding the above copyright notice to the beginning * of your source code files, and to any copyright notice that you may distribute * with programs based on this work. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * */

/**
* @file StringTokenizer.hpp
* @author tlin
* @date 09/20/2004
* @time 11:30am
* @version 1.0
*/

91. Variable (include class member variable, struct member variable, union member variable and enum member variable) should be documented right after its declaration

vector<int>::iterator i; /**< iterator */

Although Doxygen support several kinds of variable documentation, we prefer /**< ... */

92. Class, Struct, Union, typedef and function (include class member function) should be documented right before their declaration

93. Class Documentation

/**
* @class StringTokenizer StringTokenizer.hpp "util/StringTokenizer.hpp"
*
* @brief The string tokenizer class allows an application to break a string into tokens
*
* The set of delimiters (the characters that separate tokens) may be specified either
* at creation time or on a per-token basis.
* An instance of StringTokenizer behaves in one of two ways, depending on whether it was
* created with the returnTokens flag having the value true or false.
*/
class StringTokenizer{

    public:

        /**
         * Constructs a string tokenizer for the specified string. The characters in the delim argument
         * are the delimiters for separating tokens. characters are skipped and only serve as
         * separators between tokens.
         * @param str a string to be parsed.
         * @param delim the delimiters, default value is "\t\n\r".
         */
        StringTokenizer(const std::string &str, const std::string &delim = "\t\n\r");

         /**
         * Constructs a string tokenizer for the specified string. The characters in the delim argument
         * are the delimiters for separating tokens.
         * If the returnTokens flag is true, then the delimiter characters are also returned as tokens.
         * Each delimiter is returned as a string of length one. If the flag is false, the delimiter
         * characters are skipped and only serve as separators between tokens.
         * @param str a string to be parsed.
         * @param delim the delimiters.
         * @param returnTokens flag indicating whether to return the delimiters as tokens.
         */
        StringTokenizer(const std::string& str, const std::string& delim, bool returnTokens);

        /**
         * Calculates the number of times that this tokenizer's nextToken method can be called
         * before it generates an exception.
         *
         * @return the number of tokens remaining in the string using the current delimiter set.
         */
        int countTokens();

        /**
         * Tests if there are more tokens available from this tokenizer's string.
         *
         * @return true if there are more tokens available from this tokenizer's string, false otherwise
         */
        bool hasMoreTokens();

        /**
         * Returns the next token from this string tokenizer.
         *
         * @return the next token from this string tokenizer.
         *
         * @exception NoSuchElementException if there are no more tokens in this tokenizer's string
         */
        std::string nextToken();

        /**
         * Returns the next token in this string tokenizer's string. The new delimiter set remains the
         * default after this call.
         *
         * @param newDelim the new delimiters.
         *
         * @return the next token, after switching to the new delimiter set.
         *
         * @exception NoSuchElementException if there are no more tokens in this tokenizer's string.
         *
         */
        std::string nextToken(const std::string& newDelim);

        /**
         * Returns the current delimiter set of this string tokenizer
         *
         * @return the current delimiter set
         */
        std::string getDelimiter();

    private:

        /**
         * Test if character is in current delimiter set.
         *
         * @param c character to be tested
         *
         * @return true if character is in current delimiter set, flase otherwise.
         */
        bool isDelimiter(char c);

        std::string delim_;          /**< current delimiter set of this string tokenizer */

bool returnTokens_; /**< flag indicating whether to return the delimiters as tokens */
};

94. struct documentation

/**

* @struct Employee

* @brief Employee struct contains some properties of an employee object

* detail description

*/

struct Employee {

int id; /**< employee indentification number */

string firstName; /**< first name */

string lastName; /**< last name */

string title; /**< job title */

};

95. union documentation

/**

* @union Parameter

* @brief ...

* detail description

*/

union Parameter {

int intVar; /**< integer parameter */

float floatVar; /**< float parameter */

string strVar; /**< string paramter */

};

96. enum documentation

/**

* @enum Color

* @brief ...

* detail description

*/

enum Color {
    COLOR_RED,       /**< red color */
    COLOR_GREEN, /**< green color */
    COLOR_BLUE     /**< blue color */
};

97. typedef documentation

/**

* @typedef IntVector

* @brief ...

* detail description

*/

typedef std::vector<int> IntVector;

98. function documentation

/**

* @fn int open(const char *pathname,int flags) * @brief opens a file descriptor. * @param pathname the name of the descriptor. * @param flags opening flags.

* @return descriptor of the file, return -1 if error */

int open(const char *pathname,int flags);

99. template function documentation

/**

* @fn template <typename T> inline const T& max (const T &a, const T &b) * @brief Compares two objects and returns the larger of the two . * @template T object type. * @param a first parameter. * @param b second parameter.

* @return the larger object */

template <typename T>

inline const T& max (const T &a, const T &b);

100. template class documentation

/**

* @class Stack * @brief template stack class. * detail description. * @template T element type. */

template <typename T>

class Stack {

public:

void push(const T& elem ); void pop(); T top() const;

bool empty() const ;

private:

std::vector<T> elems_; };

8 References

[1] Code Complete, Steve McConnel - Microsoft Press

[2] Programming in C++, Rules and Recommendations, M Henricson, e. Nyquist, Ellemtel (Swedish telecom)
http://www.doc.ic.ac.uk/lab/cplus/c++.rules/

[3] Wildfire C++ Programming Style, Keith Gabryelski, Wildfire Communications Inc.
http://www.wildfire.com/~ag/Engineering/Development/C++Style/

[4] C++ Coding Standard, Todd Hoff
http://www.possibility.com/Cpp/CppCodingStandard.html

[5] Doxygen documentation system
http://www.stack.nl/~dimitri/doxygen/index.html