This document lists C++ coding recommendations common in the C++ development community. These style recommendations are based on use of the C++11 language standard. The provided guidance is forward compatible with C++14.
This document was derived from C++ Programming Style Guide. The recommendations are based on established standards collected from a number of sources, individual experience, local requirements/needs, as well as recommendations given in [1] - [8].
The recommendations are grouped by topic and each recommendation is numbered to make it easy to refer to during code reviews.
Layout of the recommendations is as follows:
| Recommendation short description. |
| Illustrative code (as applicable). |
| Motivation, background and additional information. |
In the guideline sections the terms should and can have special meaning. A should is a strong recommendation, and a can is a general guideline.
| . Names representing classes, structs, enums, typedefs and aliased types should be upper camel case. Names should be descriptive. Alias declarations should not depend upon other alias declarations. The _t suffix should be appended to typedefs and aliased types. |
| MyServiceClass MyVehicleConfigurationStructSuperLongName MyColorEnum namespace uxas // example of alias declaration { namespace type { using ComponentMap_t = std::unordered_map<size_t, std::shared_ptr<component::ComponentBase>>; }; }; |
| Common practice in the C++ development community. |
.
Variable names should describe the purpose of the variable. Variable names
should be lower camel case. Private and
protected class and instance variables should have the following prefixes:
Boolean variables should have the is prefix. For private and protected boolean variables, the s_ and m_ prefixes preceed the is prefix (e.g., m_isDone). |
| line // name for a line object or a pointer to a line object searchZone // example instance variable names m_line m_searchZone m_isReady // boolean variable m_points // plural name if variable is a collection of objects // example class variable names s_line s_searchZone s_isReady // boolean variable s_points // plural name if variable is a collection of objects // examples of not-allowed Hungarian notation variable names pLine // do not use Hungarian notation bSuccess // do not use Hungarian notation m_bSuccess // do not use Hungarian notation dAngle_m // do not use Hungarian notation uintDistance_m // do not use Hungarian notation s_uintDistance_m // do not use Hungarian notation |
|
Common practice in the C++ development community that minimizes variable
naming collisions and makes variables easy to distinguish.
Apart from its name and its type, the scope of a variable is its most important feature. Using s_ to Indicate class scope and m_ to indicate instance scope simplifies distinguishing these variables from local scratch variables. A beneficial side effect of this naming convention is the implied, natural convention for naming get/set accessor functions: void setDepth(int32 depth) { m_depth = depth; };
|
| . Named constants (including enumeration values) should be all uppercase using underscore to separate words. |
| constexpr int32 MAX_ITERATIONS = 25; constexpr double PI = 3.1416; |
|
Common practice in the C++ development community.
In general, the use of such constants should be minimized.
In some cases, implementing the value as a method is a better choice:
constexpr int32 getMaxIterations() { return 25; };// don't use: #define MAX_ITERATIONS = 25
This form is both easier to read, and it ensures a unified interface towards class values. |
| . Names representing methods or functions should 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. |
| . Names representing namespaces should be all lowercase and singular. |
| model::analyzer, io::iomanager, common::math::geometry |
| Common practice in the C++ development community. |
| . Names representing template types should be a single upper case letter. |
| template<class T> ... template<class C, class D> ... |
| Common practice in the C++ development community. This makes template names stand out relative to all other names used. |
| . Abbreviations and acronyms included in names should be camel case instead of all upper case [7]. |
| exportHtmlSource(); // don't use: exportHTMLSource(); openDvdPlayer(); // don't use: openDVDPlayer(); |
| Using all upper case 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 readability is seriously reduced; the word following the abbreviation does not stand out as it should. |
| . 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. |
| . Generic variables should have the same name as their type. The exceptional case is variables of basic types (e.g., int32, string, etc.), then the variable's name should describe what it represents (e.g., "totalDelay_ms"). |
| void setVehicleState(VehicleState* vehicleState, int32 timeOffset_ms) // improper: void setVehicleState(VehicleState* value1, int32 value2) // improper: void setVehicleState(VehicleState* aVehicleState, int32 anOffset) // improper: void setVehicleState(VehicleState* t, int32 o) void connect(Database* database) // improper: void connect(Database* db) // improper: 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; |
| . All names and comments should be written in English. |
| fileName; // don't use: filNavn |
| English is the preferred language for international development. |
| . Variables with a large scope should have long names, variables with a small scope can have short names [4]. |
| 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. |
| . The name of the object is implicit, and should be avoided in a method name. |
| line.getLength(); // improper: line.getLineLength(); |
| The latter seems natural in the class declaration, but proves superfluous in use, as shown in the example. |
| . The terms Get/Set should be used when naming accessor functions that provide public access to a private objects that belong to either a class or class instance. Use get (lower camel case) when naming const or non-const get accessor functions that provide protected access to a private or protected object. Reference: get/set practices rule. |
| public: const std::string& GetType() const { return (m_type); }; SetType(std::string& type) { m_type = type; }; protected: // lower camel case function name - convention for protected accessor // here, const not used, so derived classes can modify m_type via function std::string& getType() { return (m_type); }; |
| Use of get and set is a common convention in the C++ development community. This practice is widely used in the Java and C# communities. |
| . A descriptive adjective should be used for methods. The term compute can be used in methods where something is computed. The term find can be used in methods where something is looked up. |
| valueSet->computeAverage(); matrix->computeInverse(); vertex.findNearestVertex(); matrix.findMinElement(); |
| Use of "compute" provides a clue of a potentially time-consuming operation; a developer might consider caching the result. Use of "find" provides a clue of what is likely a look-up requiring minimal of computations. Consistent use of the key terms enhances readability. |
| . The term initialize should be used where an object or a concept is established. |
| vehicle.initialize(); vehicle.initializeConfiguration(); vehicle.initializeState(const VehicleState& vehicleState); |
| Do not use abbreviation init . |
| . 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. |
| . Plural form should be used on names representing a collection of objects. |
| vector<Point> points; int32 distances_m[]; |
| 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. |
| . Append the word Count to members that represent a number of items. |
| pointCount, lineCount, getPointCount() |
| The notation is taken from mathematics where it is an established convention for indicating a number of objects. |
| . Prefer iterator variable names ii, jj, kk, mm, nn, oo, pp etc.. Don't use ll since it can easily be mis-read as ii. Do not use single character names. Descriptive, longer names are permissible. |
| for (int32 ii = 0; ii < tables.getCount(); ii++) { for (int32 jj = 0; jj < tables[ii].getRowCount(); jj++) { for (int32 kk = 0; kk < tables[ii].getColumnCount(); kk++) { ... tables[ii].setCell(jj, kk, value); } } } for (vector<MyClass>::iterator myClassIt = list.begin(); myClassIt != list.end(); myClassIt++) { Element element = *myClassIt; ... } |
|
Use of the xx name pattern for the index variable streamlines
analysis of loop behavior. It is especially beneficial in nested loop
analysis. Similar benefits are obtained from longer, descriptive names.
Prefer reserving jj, kk, mm, nn, etc. variables for nested loops. |
| . The prefix is should be used for boolean methods that return a boolean property or characteristic of the object. Exclude the is prefix for cases when a boolean is returned by a function that primarily performs processing (e.g., performWork method that returns a boolean indicating outcome of performing work). See variable name conventions. |
| 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 fit better in some situations. These are the has and can prefixes:
bool hasRadar(); bool canEvaluate(); |
| . Complement names should be used for complement operations [4]. |
| 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. |
| . Abbreviations in names should be avoided. |
| computeAverage(); // do not use: compAvg(); |
|
There are two types of words to consider.
First are the common words listed in a language dictionary.
These should never be abbreviated. Never write:
cmd instead of command 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 |
| . Negated boolean variable names should be avoided. |
| bool isError; // don't use: isNoError bool isFound; // don't use: isNotFound |
| The problem arises when such a name is used in conjunction with the logical negation operator as this results in a double negative. The meaning of !isNotFound is not immediately apparent. |
| . Names of enumeration constants should be singular (e.g., Color, Type, State) instead of plural (e.g., Colors, Types, States). Enumeration constant names may be prefixed by a common type name. |
| enum class Color // scoped enumeration due to use of "class" keyword { RED, // no common name prefix GREEN, BLUE }; enum class Color { COLOR_RED, // "COLOR" common name prefix 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. The enum name should be singular as in enum Color {...}. A plural name like enum Colors {...} may look fine when declaring the type, but is less readable when used. |
| . 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. |
| . Functions (methods returning something) should be named after what they return and procedures (void methods) after the processing that they perform. |
| int32 getTotalCount(); void computeMeanValue(); |
| 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. |
| . A class should be declared in a header file and defined in a source file. The header and source files for a class should have .h and .cpp extensions, respectively. |
| MyClass.h, MyClass.cpp |
| Adhere to common C++ standards for declaration, implementation and file extensions. |
.
All definitions should reside in source files with
four exceptions:
|
| class MyClass // within MyClass.h { public: // get/set accessor functions const std::string& GetName() const { return return m_name; }; void SetName(const std::string& name) { m_name = name; }; // deleted functions. // add info or link to programming practices bool isEven(char) = delete; // prevent invoking isEven with char parameter bool isEven(bool) = delete; // prevent invoking isEven with bool parameter bool isEven(double) = delete; // prevent invoking isEven with double or float parameter // default copy constructor and copy operator MyClass(const MyClass&) = default; // explicit declaration of default implementation MyClass& operator=(const MyClass&) = delete; // delete unwanted copy assignment operator // deleted move constructors and move operator MyClass(const MyClass&&) = delete; // delete unwanted move constructor MyClass& operator=(const MyClass&&) = delete; // delete unwanted move assignment operator protected: virtual bool performWork() { return (false); }; }; |
| Header files declare an interface. The header files should also contain simple, one line implementations are placed in the When looking for an implementation, the programmer should always know that it is found in the source file. |
| . Prefer file content limited to 120 columns; file content up to 160 columns is allowable. |
| Limiting content columns improves readability since it avoids default editor word-wrap behavior and increases consistency of coding across the team. |
| . Special characters such as TAB and page break control characters should be avoided. In IDEs, configure indentation to consist of spaces. |
| These characters often cause problems for editors, printers, terminal emulators or debuggers - especially if used in a multi-programmer, multi-platform environment. |
| . Make obvious splitting for cases of incomplete lines [4]. |
| totalSum = a + b + c + d + e; function (param1, param2, param3); setText ("Long line split" "into two parts."); for (int32 tableIndex = 0; tableIndex < tableCount; tableCount += tableCountStep) { ... } |
|
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:
|
| . Header files should contain an include guard. |
| #ifndef CLASSNAME_H #define CLASSNAME_H ... #endif // COM_COMPANY_MODULE_CLASSNAME_H |
| #ifndef COM_COMPANY_MODULE_CLASSNAME_H #define COM_COMPANY_MODULE_CLASSNAME_H ... #endif // COM_COMPANY_MODULE_CLASSNAME_H |
| The construction is to avoid compilation errors. The name convention resembles the location of the file inside the source tree and prevents naming conflicts. |
.
Include statements should be sorted and grouped by their
hierarchical position in the system with low level files included last.
Headers should not be dependent upon other headers (C/C++ include file order/best practices).
Within a group, include statements should be alphabetically sorted.
Leave an empty line between groups of include statements.
|
| #include "com/company/ui/MainWindow.h" #include "com/company/ui/PropertiesDialog.h" #include <qt/qbutton.h> #include <qt/qtextfield.h> #include <fstream> #include <iomanip> |
|
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 should never be absolute. Compiler directives should instead be used to indicate root directories for includes. |
| . Include statements should 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. |
| . Types that are local to one file should be declared inside that file. For example, a type that is only used in a source file should be declared in the source file instead of its associated the header file. |
| Enforces information hiding. |
| . Type conversions should always be done explicitly. Never rely on implicit type conversion. |
| floatValue = static_cast<float>(intValue); // don't use: floatValue = intValue; |
| By this, the programmer indicates that he is aware of the different types involved and that the mix is intentional. |
| . Prefer initializing variables where they are declared. |
|
This ensures that variables are valid at any time. For limited cases, it is
impractical to initialize a variable to a valid value where it is declared:
int32 x, y, z; getCenter(&x, &y, &z); In these cases, variables should be left uninitialized rather than initialized to irrelevant values. |
| . Declare a pointer or reference variable by placing the asterisk or ampersand adjacent to the type name. C++ pointers and references should have their reference symbol next to the type rather than to the name. |
| float* x; // don't use: float *x; int32& y; // don't use: int32 &y; char* m_name; const string& m_defaultMessage; |
| The pointer-ness or reference-ness of a variable is a property of the type rather than the name. Placing the asterisk or ampersand adjacent to the variable name is a style used in C-programming. This convention aligns with common C++ programming practices. |
| . Variable names should have distinctive meaning. |
| Enhance readability by ensuring all concepts are represented uniquely. Reduce chance of error by side effects. |
| . Variables names should explicitly describe associated units. Unit representation is appended to the end of the variable name. |
| int32 distance_m; // _m denotes meters int32 edgeDistance_ft; // _ft denotes feet int32 vehicleMass_kg; // _kg denotes kilograms int32 vehicleSpeed_mps; // _mps denotes meter per second real32 vehicleAcceleration_kgmps2; // _kgmps2 denotes kilogram meters per second squared int32 eventDuration_s; // _s denotes seconds int32 dataSampleInterval_ms; // _ms denotes milliseconds real32 angle_deg; // _deg denotes degrees real32 angle_rad; // _rad denotes radians real32 angle_grad; // _grad denotes grads |
| Non-ambiguous representation of units. |
| . Implicit boolean test should not be used other than for boolean variables. |
| if (lineCount != 0) // don't use: if (lineCount) if (distance_m != 0.0) // don't use: if (distance_m) |
|
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.
Test pointers using nullptr, i.e. if (pValue != nullptr). Do not implicitly pointers for 0 or NULL. |
| . 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. |
| . Order of function parameters should be inputs following by outputs. |
| MyObject MyObjectEventHandler::GetUpdatedMyObject(const MyObjectEvent& event, MyObject& myObject) { ... } |
| Ordering improves understandability. |
| . Loop variables should be initialized immediately before the loop. Instructions inside of a for() statement should be limited to loop control statements. |
| sum = 0; for (ii = 0; ii < 100; ii++) // don't use: for (sum = 0, ii = 0; ii < 100; ii++) { ... sum += value[ii]; } isWorking = true; while (isWorking) { ... if (conditions) { isWorking = false; // discontinue loop processing } } |
| Increase maintainability and readability. Make a clear distinction of between loop controls and what is contained inside of the loop. |
| . Use while (true) for infinite loop implementation. |
| bool isError = false; while (true) { ... if (isLoopingDone) { break; // discontinue loop processing } if (isError) { break; // discontinue loop processing } } for (;;) // improper implementation { ... } while (1) // improper implementation { ... } |
| Testing against true provides the greatest readability. Testing against 1 is not meaningful. The form for (;;) has very poor readable; it obscures the infinite loop. |
| . Prefer placing the normative case into the if block and the less common case in the else block of an if-else statement [4]. If the normative case consists of many lines of code and the non-normative case is a few lines of code, then it is okay to place the non-normative case in first block. For less complex if/else if/else implementations, favor returning from the last line of a function. For more complex if/else if/else implementations (especially validation logic, such as parameter validation), favor the simplicity of returning from the inside of a conditional blocks. This approach often avoids deeply nested code blocks that are difficult to read. |
| if (condition) { ... } bool isOk = readFile (fileName); if (isOk) // normative case first { ... } else { ... } if (!isOk) // non-normative case first (less common, but okay) { ... a few lines of code ... } else { ... normative case has many, many lines of code ... ... so for this case, place in second block ... } if (condition) { ... } else if (condition) { ... } else { ... } // Prefer use of multiple return statements // to enhance simplicity and readability over // adding another variable to represent return value if (1st_invalid_condition) { return (false); } else if (2nd_invalid_condition) { return (false); } if (1st_valid_condition) { ... return (true) } else if (2nd_valid_condition) { ... return (true) } else if (3rd_valid_condition) { ... return (true) } else if (4th_valid_condition) { ... return (true) } else // first three conditions are false { ... return (true) } |
| Better readability and reduced maintenance complexity. |
| . Prefer multiple return statements instead of adding another variable to represent return value for the case of multiple catch blocks (enhance simplicity and readability). |
| // For the case of multiple catch blocks, prefer returning from within the catch block (less complex logic). try { ... return (true); } catch (Exception& mostCommonException) { ... return (false); } catch (Exception& lessCommonException) { ... return (false); } catch (Exception& rareException) { ... return (false); } catch (Exception& anyOtherException) { ... return (false); } |
| Avoids introduction of another variable for return purpose only. This is important for both the readability and performance. |
| . The conditional should be put on a separate line followed by enclosing in braces on separate lines. This rule applies even if the block contains a single statement. |
| if (isDone) // do not implement as a single line: if (isDone) doCleanup(); { doCleanup(); } |
| This is for debugging purposes. When writing on a single line impairs debugging since it is not apparent whether the test is true or false. Use of braces improves readability. |
| . Executable statements in conditionals should be avoided. |
| File* fileHandle = open(fileName, "w"); if (fileHandle != nullptr) { ... } // improper implementation 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++. |
| . For conditional statements containing multiple conditions, logically group and organize for best readability. Prefer limiting the number of conditions on a single line to one or two. Use parentheses to assure readability of the intended logic. For complex conditional expressions, introduce temporary boolean variables [4]. |
| if (aaaaa1 > aaaaa2 && bbbbb1 == bbbbb2 && ccccc1 && (ddddd1 || eeeee1)) { ... } // improper if (aaaaa1 > aaaaa2 && bbbbb1 == bbbbb2 && ccccc1 && (ddddd1 || eeeee1)) { ... } // // introduce temporary boolean variables for complex logic cases // bool isFinished = (elementIndex < 0) || (elementIndex > maxElementIndex); bool isRepeatedEntry = elementIndex == lastElement; if (isFinished || isRepeatedEntry) { ... } |
| Make conditionals easier to read, debug and maintain by not placing many conditionals on a single line. Assignment of boolean expressions to temporary boolean variables can enhance readability and documentation. |
| . The use of hard-coded numbers in the code should be avoided. Numbers other than 0 and 1 should instead be declared as named constants. |
| 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. |
| . Floating point constants should always be written with decimal point and at least one digit both before and after the decimal point. |
| real32 total = 0.0; // don't use: real32 total = 0; real32 speed = 3.0e8; // don't use: real32 speed = 3e8; real32 length = 0.5; // don't use: real32 length = .5; real32 sum; ... sum = (a + b) * 10.0; |
| The number and expression system in C++ is borrowed from mathematics, so best practice is to adhere to mathematical conventions for syntax wherever possible. 0.5 is a lot more readable than .5; |
| . Functions should always have the return value type explicitly present. |
| int32 // type explicitly implemented getValue() // improper (no return type): getValue() { ... ... } |
| If not exlicitly present, C++ implies int return value for functions. A programmer should never rely on this feature, since this might be confusing for programmers not aware of this artifact. |
| . Never use goto. |
| 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. |
| . Set native pointers to null value by using nullptr. Do not set to 0 or NULL. |
| string* p = nullptr; |
| Use of nullptr replaces use of 0 in C++11. NULL is part of the standard C library; it has become obsolete in C++. |
.
Class declarations and definitions should be sorted
public, protected and private [5][4].
Leave out sections that do not apply. Order within sections
should be as follows [3]:
|
| class MyDerivedClass : public MyBaseClass { public: ... protected: ... private: ... } |
| This aligns with the general block rule. |
| . Basic indentation should be four spaces. Do not use tab characters. In most Integrated Development Environments (IDEs), use of spaces can be specified via code formatting configuration settings. |
| for (ii = 0; ii < elementCount; ii++) { a[ii] = 0; } |
| Indentation of one is too small to emphasize the logical layout of the code. Indentation larger than four makes deeply nested code difficult to read and increases the chance that the lines should be split. Choosing between indentation of two, three and four, two and four are the more common. |
| . Block layout for namespaces and classes (braces not indented) is shown in the first example. The second example illustrates block layout for functions, loops and control statements. All open/close braces are column aligned. Blocks containing a single statement should be enclosed by column-aligned braces. Do use not the bracing layout shown in the third example [7]. | mynamespaceA // fiat bracing (no indent of braces) { mynamespaceB { mynamespaceC { MyClass // class block layout (no indent of braces) { public: ... DoSomething(); ... }; }; }; }; while (!isDone) // functions, loops and control statements block layout { doSomething(); isDone = calcuateProcessingCompleted(); } while (!isDone) // do not use this indentation style { doSomething(); isDone = calcuateProcessingCompleted(); } // function void someFunction() { ... } // for for (initialization; condition; update) { ... } // while while (condition) { ... } // do-while loops (minimize do-while loops) do { ... } while (condition); // try-catch try { ... } catch (Exception& exception) { ... } // single statement if-else, for or while statements should be written with brackets. if (condition) { x = y + z; } while (ii < maxCount) { ii++; } for (initialization; condition; update) { count++; } switch (condition) { case ABC : ... // fall-through (insert comment documenting intent of falling through) case DEF : ... break; case XYZ : ... break; default : ... break; } | |
| . Empty for statements should be avoided. |
| for (initialization; condition; update) ; |
| The format of the example 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. |
| . . 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. |
.
General whitespace practices.
|
| a = (b + c) * d; // improper syntax (missing spaces): a=(b+c)*d while (true) // don't use: while(true) { ... } doSomething(a, b, c, d); // improper: doSomething(a,b,c,d); case 100 : // don't use: case 100: for (ii = 0; ii < 10; ii++) // improper: for(ii=0;ii<10;ii++) { ... } |
| 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. |
| . Method names should not be followed by a white space in general, including when it is followed by another name. |
| doSomething(currentFile); |
| Promotes semantic consistency across the code base. |
| . 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. |
| . 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. |
| . Use alignment to enhance 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. |
| . Code should be implicitly informative and have complementary information in comments. Comments relating to long-term objectives, development roadmap or persistent issues should start with keywords (TODO, REVIEW, DESIGN, ISSUE, ROADMAP), date and initials of developers to enhance discovery. Implementing complex, cryptic code should be avoided to minimize extensive explanation via extensive commenting. [4] |
| // TODO 20150507 dbk // optimize area search algorithm (assess linear vs. non-linear methods) // TODO ROADMAP 20150918 rjt // revise telemetry implementation to depend on std::chrono // reduce dependency on Boost library // TODO REVIEW 20151118 rjt // review messaging paradigm design to assure // coherence of communication with other systems // DESIGN 20150911 rjt message addressing - entity ID // - received/sent LMCP messages always include entity ID // - the entity cast address is derived from entity ID (see getEntityCastAddress function) // DESIGN 20150825 dbk, rjt notional configuration XML design notes // ISSUE 20151118 rjt (nuisance issue) // Due Google Test's single-threaded implementation and // the UxAS's multi-threaded implementation, nuisance errors // can occur and should be ignored. |
| In general, the use of comments should be minimized by making the code self-documenting by appropriate name choices and an explicit logical structure. |
| . Use // for all comments, including multi-line comments within a function. /* ... */ block comments are okay for member and class descriptions. |
| // 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. |
| . Comments should be included relative to their position in the code. [4] |
| while (true) { // Do something descriptive comment something(); } |
| Minimize comments that break the logical structure of the code. |
| . For large sections of code, add editor-fold comments to the start and end of each section to enable "folding" (collapsing) the large code section. |
| /*! @name Public Accessor Functions * */ // <editor-fold defaultstate="collapsed" desc="Get and Set Accessors FOLD"> static constexpr std::int32_t GetCount() { return (s_Count); }; // </editor-fold> |
| Simplifies code maintenance since it enables only viewing sections of code that are relevant to a the coding task at hand. |
| . Class and method header comments should follow the JavaDoc style Doxygen conventions. |
| /** * \brief The getStatusMessage function returns status string message containing * the the object's status string and input parameters id and time. * \param id * \param time * \return status message string */ const std::string& getStatusMessage(std::int32_t id, std::time_t time) const { std::ostringstream strStream; strStream << "Status for " << std::to_string(id) << " is " m_status << " at time " << std::to_string(time); return strStream.str(); } void foo(int v /**< [in] docs for input parameter v. */); /** \brief Brief description. * Brief description continued. * * Detailed description starts here. * @param id * @param time * @return */ const std::string getActionMessage(std::int32_t id) const |
| Doxygen documentation is similar to Java documentation which is more mature than C/C++ documentation community practices. Doxygen helps produce high quality hypertext documentation from source code comments that adhere to Doxygen-compliant comment syntax. |
| . Code comments (especially file header block comments) should include the following documentation tags (as applicable): |
| \file \class \name \brief \author \warning \param |
| Documentation tags enable use of automated documentation (e.g., Doxygen ). |
[1] C++ Programming Style Guidelines
[2] C++ Programming Practice Guidelines
[4] Code Complete, Steve McConnell - Microsoft Press, 2004
[5] Programming in C++, Rules and Recommendations, M. Henricson / E. Nyquist, 1992
[6] Wildfire C++ Programming Style, Keith Gabryelski, Wildfire Communications, 1997