-
Notifications
You must be signed in to change notification settings - Fork 38
Cpp Coding Style Guidelines
NOTE: WE NO LONGER USE THIS GUIDE! Use the Google style guide Instead!
Google style guide It is short, well explained and widely used.
Geotechnical Software Services © 1996 - 2011
Google Inc Revision 3.245 © 2013
Edits © Paul Furgale, Hannes Sommer, Simon Lynen 2013
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. The 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 maximise its readability independent of any IDE.
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:
Example if applicableMotivation, 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.
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.
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.
The attempt is to make a guideline, not to force a particular coding style onto individuals. Experienced programmers normally want to 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. Names representing types must be in mixed case starting with upper case.
Line, SavingsAccountCommon practice in the C++ development community.
line, savings_accountCommon 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. Discussion
MAX_ITERATIONS, COLOR_RED, PICommon 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 #define MAX_ITERATIONS 25
{
return 25;
}This form is both easier to read, and it ensures a unified interface towards class values.
In cases where the value is needed as a constant expression two possibilities are encourages:
constexpr int getMaxIterations() // NOT #define MAX_ITERATIONS 25
{
return 25;
}Or defining an enum:
enum MyConstants //the enum name is a type and therefore written mixed-case
{
MAX_ITERATIONS = 25,
}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 distinguishable from variables by their specific form.
model::analyzer, io::iomanager, common::math::geometrytypedef std::vector<cv::Point> PointVector; //NOT: PointVector_t, NOT: PointVector_type
typedef boost::shared_ptr<aslam::Camera> CameraPtr; //NOT: Camera_ptrUsing the same naming convention as for types allows easier exchange in cases where a typename is replaced by an actual type later. Discussion.
9. Names representing template parameters should be named like types but with an trailing underscore or with a single capital letter in case there are few arguments and their meaning is clear.
While their use is exchangeable for template parameters, typename should be preferred to class as template parameter specifier.
template<typename T> ...
template<int Rows_, bool RowMajor_, typename SortingFunctor_, typename ValueType_> ...Common practice in the C++ development community. This makes template names stand out relative to all other names used. Discussion
exportHtmlSource(); // NOT: exportHTMLSource();
openDvdPlayer(); // NOT: openDVDPlayer();Using all uppercase for the base name will give conflicts with the naming conventions given above. A variable of this type would 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.
::mainWindow.open(), ::applicationContext.getName()In general, the use of global variables should be avoided. Consider using singleton objects instead.
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. Discussion
void setTopic(Topic* topic) // NOT: void setTopic(Topic* value)
// NOT: void setTopic(Topic* aTopic)
// NOT: void setTopic(Topic* t)
void connect(Database* database) // NOT: void connect(Database* db)
// NOT: 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;fileName; // NOT: filNavnEnglish is the preferred language for international development.
14. 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 of a few lines of code. Common scratch variables for integers are i, j, k, m, n and for characters c and d.
line.getLength(); // NOT: line.getLineLength();The latter seems natural in the class declaration, but proves superfluous in use, as shown in the example.
17. The terms get/set must be used where an attribute is accessed directly. Use getVariableRef() if a reference is returned:
employee.getName();
employee.setName(name);
matrix.getElement(2, 4);
matrix.setElement(2, 4, value);
person.getAgeRef();Common practice in the C++ development community. In Java this convention has become more or less standard. Discussion about how to handle references
###18. 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 potentially time-consuming operation, and if used repeatedly, he might consider caching the result. Consistent use of the term enhances readability. ##22. Plural form should be used on names representing a collection of objects.
vector<Point> points;
int values[];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 its elements. ###23. The prefix n should be used for variables representing a number of objects.
nPoints, nLines###24.The suffix No should be used for variables representing an entity number.
tableNo, employeeNoThe 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.
###25. Iterator variables should be called i, j, k if the loop is rather small (less than 10 lines) For larger loops it makes sense to use names sufficed by idx:
for (int i = 0; i < nTables); ++i) {
:
}
for (int pointIdx = 0; pointIdx < nPoints); ++pointIdx) {
:
//potentially lots of code
:
}The notation is taken from mathematics where it is an established convention for indicating iterators. Variables named j, k etc. should be used for nested loops only. This also follows the rule of having longer names for variables with larger scope.
Iterators should be called it
for (vector<MyClass>::iterator it = list.begin(); it != list.end(); ++it) {
Element element = *it;
...
}###26. The prefix is should be used for boolean variables and methods.
isSet, isVisible, isFinished, isFound, isOpenCommon 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 fit better in some situations. These are the has, can and should prefixes:
bool hasLicense();
bool canEvaluate();
bool shouldSort();###27. 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, open/close, show/hide, suspend/resume, etc.Reduce complexity by symmetry. ###28. Abbreviations in names should be avoided.
computeAverage(); // NOT: 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.
###29. Naming pointers specifically should be avoided.
Line* line; // NOT: Line* pLine;
// NOT: 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 emphasize the type. 30. Negated boolean variable names must be avoided.
bool isError; // NOT: isNoError
bool isFound; // NOT: isNotFoundThe 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. ###31. 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.
Note also that the enum name typically should be singular as in enum Color {...}. A plural name like enum Colors {...} may look fine when declaring the type, but it will look silly in use.
The C++11 enum class specifier can be used. The values cannot be implicitly converted to int anymore enforcing additional type-safety.
enum class Enumeration {
Val1,
Val2,
Val3 = 100,
Val4 // = 101
};###32. 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. ###33. 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
###34. C++ header files should have the extension .hpp (preferred) or .h. Source files should have the extension .cpp.
MyClass.cpp, MyClass.hpp
These are all accepted C++ standards for file extension. ###35. 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.
include/MyClass.hpp, src/MyClass.cppThis makes it easy to find the associated files of a given class.
An exception is template classes that must be both declared and defined inside a .hpp file. In this case it is good practise to put the implementing header file in a separate implementation folder.
include/MyTemplatedClass.hpp, include/implementation/MyTemplatedClass.hppAnother important exception is when a class requires some additional structures / classes. If for internal usage or as helper class for its users or hidden virtual implementations for a public interfaces. Those 'satellite' classes can be grouped together with the 'main' class in its source file and - if necessary - also in its (implementing) header file. Discussion
###36. All definitions should reside in source files. Except the definition needs to stay in an included file (inline functions or any templated definition). Then it should be in a separate implementation header which is included at the end of the declaring header. Only definitions that are also very short and trivial as simple getters, setters or constructors with short initialization lists only or empty function implementations may be written directly in the declaring header file. Discussion
A non-templated class in MyClass.hpp:
...
class MyClass
{
public:
int getValue () const {return value_;} // NO, unless inlining required.
...
private:
int value_;
};
...A templated class in MyTemplatedClass.hpp:
...
template<typename T>
class MyTemplatedClass
{
public:
virtual ~MyTemplatedClass(){} // Okay because trivial and templated.
int getValue () const {return value_;} // Okay because trivial and templated.
int calcComplicated(); // Only declaration in this header file because its definition is nontrivial.
...
private:
int value_;
};
#include "implementation/MyTemplatedClass.hpp"
...##4.2 Include Files and Include Statements
###40. Header files must contain an include guard.
#ifndef COM_COMPANY_MODULE_CLASSNAME_H
#define COM_COMPANY_MODULE_CLASSNAME_H
:
#endif // COM_COMPANY_MODULE_CLASSNAME_HThe construction is to avoid compilation errors. The name convention resembles the location of the file inside the source tree and prevents naming conflicts. ###41. 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. The order of includes should be: C libs / C++ stl / ... / local includes. Local includes should be included using " ", others using <>. The include statements should be grouped by libraries.
#include <fstream>
#include <iomanip>
#include <qt/qbutton.h>
#include <qt/qtextfield.h>
#include "com/company/ui/PropertiesDialog.h"
#include "com/company/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.
###42. Avoid nested includes, all what the class needs should be included, for clarity Include all files which are required in the current translation unit. Do not rely on the include being done earlier up the include hierarchy.
###42b. 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
###43. Types that are local to one file only can be declared inside that file. Enforces information hiding. ###44. 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. ###45. Type conversions should always be done explicitly. You should not rely on implicit type conversion.
floatValue = static_cast<float>(intValue); // NOT: floatValue = intValue;By this, the programmer indicates that he is aware of the different types involved and that the mix is intentional. ##5.2 Variables
###46. Variables should be initialized where they are declared. 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.
###47. Variables must never have dual meaning. Enhance readability by ensuring all concepts are represented uniquely. Reduce chance of error by side effects. ###48. 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. ###48b. Use of static variables should be minimized. In C++ there only a few situations where static variables need to be used at all. One example is the Singleton pattern. In most other cases static variables should be replaced by enums. ###49. 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].
###51. C++ pointers and references should have their reference symbol next to the type rather than to the name.
float* x; // NOT: float *x;
int& y; // NOT: int &y;The pointer-ness or reference-ness of a variable is a property of the type rather than the name. C-programmers often use the alternative approach, while in C++ it has become more common to follow this recommendation.
###55. Implicit test for 0 should not be used other than for boolean variables and pointers.
if (nLines != 0) // NOT: if (nLines)
if (value != 0.0) // NOT: if (value)It is not necessarily defined by the C++ standard that ints and floats 0 are implemented as binary 0. Also, by using an explicit test the statement gives an immediate clue of the type being tested. It is common also to suggest that pointers shouldn't test implicitly for 0 either, i.e. if (line == 0) instead of if (line). The latter is regarded so common in C/C++ however that it can be used.
###70. Test of a pointer should use the C++11 nullptr type or implicit conversion to it instead of comparing against NULL / 0.
if (data != nullptr) // NOT: if (data == NULL)
if(data) //NOT: if (data == 0)###56. 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
###57. Only loop control statements must be included in the for() construction.
sum = 0; // NOT: for (i = 0, sum = 0; i < 100; i++)
for (i = 0; i < 100; i++) sum += value[i];
sum += value[i];Increase maintainability and readability. Make a clear distinction of what controls and what is contained in the loop. ###58. Loop variables should be initialized immediately before the loop.
isDone = false; // NOT: bool isDone = false;
while (!isDone) { // :
: // while (!isDone) {
} // :
// }###59. 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.
###60. 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
###61. Complex conditional expressions must be avoided. Introduce temporary boolean variables instead [1].
bool isFinished = (elementNo < 0) || (elementNo > maxElement);
bool isRepeatedEntry = elementNo == lastElement;
if (isFinished || isRepeatedEntry) {
:
}
// NOT:
if ((elementNo < 0) || (elementNo > maxElement)||
elementNo == lastElement) {
:
}By assigning boolean variables to expressions, the program gets automatic documentation. The construction will be easier to read, debug and maintain. ###62. The nominal case should be put in the if-part and the exception in the else-part of an if statement [1].
bool isOk = readFile (fileName);
if (isOk) {
:
}
else {
:
}Makes sure that the exceptions don't obscure the normal path of execution. This is important for both the readability and performance. ###63. The conditional should be put on a separate line. While not being necessary, the use of curly brackets around the statement is encouraged.
if (isDone) // NOT: if (isDone) doCleanup();
doCleanup();
if (isDone){ // NOT: if (isDone) doCleanup();
doCleanup();
}This is for debugging purposes. When writing on a single line, it is not apparent whether the test is really true or not.
###64. Executable statements in conditionals must be avoided.
File* fileHandle = open(fileName, "w");
if (!fileHandle) {
:
}
// NOT:
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 Miscellaneous
###65. Take care of the default generated functions Default constructor, Copy constructor, Assignment, Destructor, C++11 adds move constructor and move assignment operator
###65. Whenever possible, use forward declaration, and include statement in the cpp file
###65. Use design patterns whenever it applies
###65. Add unit tests to test your code Adding unit tests allows easy verification and motivates a code style which breaks down complex algorithms in individual modules, thus reducing code duplication.
###65. Never have lengthy files or functions, this usually indicates a problem in the project structure Optimally functions should be shorter than 300 lines and contain a single functionality which can also be tested externally. Separation in several translation units speeds up compilation time and improves clarity.
###65. Introduce a good serialization scheme right from the beginning of the design (binary and ASCII) Make yourself familiar with boost serialization and the many wrappers available at the ASL code source.
###65. Whenever possible, avoid too many dependencies on external libraries Before adding a dependency to an external library for just a few function calls, think about whether the functionality can't also be provided by an existing dependency or implemented inside your project.
###65. Add a namespace around your project, this helps integration with other projects. Using namespaces keeps the global namespace clean and avoids ambiguity of names for types, methods etc.
###65. 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. ###66. 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 emphasizes the different nature of integer and floating point numbers. Mathematically the two model completely different and non-compatible concepts. Also, as in the last example above, it emphasizes the type of the assigned variable (sum) at a point in the code where this might not be evident.
###67. 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. ###68. Functions must always have the return value explicitly listed.
int getValue() // NOT: getValue()
{
:
}If not explicitly 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. ###68b. Unused function parameters should have a name comment instead of a name
int foo(int usedParameter, int /*unusedParameter*/)
{
return usedParameter;
}This declares in a portable way that this parameter is consciously unused and allows to enable compiler warnings for unused parameters that help to find accidentally unused parameters.
If the parameter's use is dependent on preprocessor macros this solution is not applicable. This happens for example when the parameter is used only in a assertion, which is removed in release builds. In that case a commented fake usage is recommended:
int foo(std::string possibly UsedParameter)
{
static_cast<void>(possiblyUsedParameter); // possiblyUsedParameter is used only when NDEBUG is not defined
...
#ifndef NDEBUG
std::cout << conditionallyUsed << std::endl;
#endif
}###69. goto should not be used. Goto statements violate 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.
#6 Layout and Comments ##6.1 A copyright banner should be included at the top of every file
##6.2 The license file corresponding to the copyright license should be included in the project
##6.3 Use doxygen to document at least all public interfaces
##6.1 Auto Formatting of Indentations A discussion about the code formatter can be found here: Formatter
###71. Basic indentation should be 2.
for (i = 0; i < nElements; i++)
a[i] = 0;Indentation of 1 is too small to emphasize the logical layout of the code. Indentation larger than 4 makes deeply nested code difficult to read and increases the chance that the lines must be split. ###72. Block layout should be as illustrated in example 1 below (recommended) or example 2, and must not be as shown in example 3 [4]. Function and class blocks must use the block layout of example 2.
while (!done) {
doSomething();
done = moreToDo();
}
###73. The class declarations should have the following form:
class SomeClass : public BaseClass
{
public:
...
protected:
...
private:
...
}This follows partly from the general block rule above. ###74. Method definitions should have the following form:
void someMethod()
{
...
}This follows from the general block rule above. ###75. 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;
}This follows partly from the general block rule above. However, it might be discussed if an else clause should be on the same line as the closing bracket of the previous if or else clause:
if (condition) {
statements;
} else {
statements;
}The chosen approach is considered better in the way that each part of the if-else statement is written on separate lines of the file. This should make it easier to manipulate the statement, for instance when moving else clauses around. ###76. A for statement should have the following form:
for (initialization; condition; update) {
statements;
}This follows from the general block rule above. ###77. An empty for statement should have the following form:
for (initialization; condition; update)
;This emphasizes 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. ###78. A while statement should have the following form:
while (condition) {
statements;
}This follows from the general block rule above. ###79. A do-while statement should have the following form:
do {
statements;
} while (condition);This follows from the general block rule above. ###80. A switch statement should have the following form:
switch (condition) {
case ABC :
statements;
// Fallthrough
case DEF :
statements;
break;
case XYZ :
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. ###81. 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 statements. ###82. 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 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. A common argument against this syntax is that the code will break if an additional statement is added without also adding the brackets. In general however, code should never be written to accommodate for changes that might arise. ###83. The function return type can be put in the left column immediately above the function name.
void
MyClass::myMethod(void)
{
:
}This makes it easier to spot function names within a file since they all start in the first column. ##6.2 Auto Formatter White Space
###84.
- 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 statements should be followed by a space character.
a = (b + c) * d; // NOT: a=(b+c)*d
while (true) // NOT: while(true)
{
...
doSomething(a, b, c, d); // NOT: doSomething(a,b,c,d);
case 100 : // NOT: case 100:
for (i = 0; i < 10; i++) { // NOT: 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. ###85. Method names can be followed by a white space when it is followed by another name.
doSomething (currentFile);Makes the individual names stand out. Enhances readability. When no name follows, the space can be omitted (doSomething()) since there is no doubt about the name in this case. An alternative to this approach is to require a space after the opening parenthesis. Those that adhere to this standard usually also leave a space before the closing parentheses: doSomething( currentFile );. This do make the individual names stand out as is the intention, but the space before the closing parenthesis is rather artificial, and without this space the statement looks rather asymmetrical (doSomething( currentFile);).
###86. Logical units within a block should be separated by one blank line.
Matrix4x4 matrix = new Matrix4x4();
double cosAngle = Math.cos(angle);
double sinAngle = Math.sin(angle);
matrix.setElement(1, 1, cosAngle);
matrix.setElement(1, 2, sinAngle);
matrix.setElement(2, 1, -sinAngle);
matrix.setElement(2, 2, cosAngle);
multiply(matrix);Enhance readability by introducing white space between logical units of a block. ###87. Methods should be separated by three blank lines. By making the space larger than space within a method, the methods will stand out within the class. ###88. Variables in declarations can be left aligned.
AsciiFile* file;
int nPoints;
float x, y;Enhance readability. The variables are easier to spot from the types by alignment. ###89. Use alignment wherever it enhances readability.
if (a == lowValue) compueSomething();
else if (a == mediumValue) computeSomethingElse();
else if (a == highValue) computeSomethingElseYet();
value = (potential * oilDensity) / constant1 +
(depth * waterDensity) / constant2 +
(zCoordinateValue * gasDensity) / constant3;
minPosition = computeDistance(min, x, y, z);
averagePosition = computeDistance(average, x, y, z);
switch (value) {
case PHASE_OIL : strcpy(phase, "Oil"); break;
case PHASE_WATER : strcpy(phase, "Water"); break;
case PHASE_GAS : strcpy(phase, "Gas"); break;
}There are a number of places in the code where white space can be included to enhance readability even if this violates common guidelines. Many of these cases have to do with code alignment. General guidelines on code alignment are difficult to give, but the examples above should give a general clue. ##6.3 Comments
##90. Tricky code should not be commented but rewritten! [1] In general, the use of comments should be minimized by making the code self-documenting by appropriate name choices and an explicit logical structure. ##91. All comments should be written in English [2]. In an international environment English is the preferred language. ##92. 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.
- Class and method header comments should follow the JavaDoc conventions. Regarding standardized class and method documentation the Java development community is more mature than the C/C++ one. This is due to the standard automatic Javadoc tool that is part of the development kit and that help producing high quality hypertext documentation from these comments. There are Javadoc-like tools available also for C++. These follows the same tagging syntax as Javadoc. See for instance Doc++ or Doxygen.
#7 References
[1] Code Complete, Steve McConnell - 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%2b%2b.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.htm
[5] Doxygen documentation system http://www.stack.nl/~dimitri/doxygen/index.html