C++ 编码规范 （2）

4 Files

4.1 Source Files

34. C++ header files should have the extension .h. Source files can have the extension .c++ (recommended), .C, .cc or .cpp.

MyClass.c++, MyClass.h

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.

MyClass.h, MyClass.c++

Makes it easy to find the associated files of a given class. An obvious exception is template classes that must be both declared and defined inside a .h file.

 

36. 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.

 

37. 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.

 

38. 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.

 

39. 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 (int 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

40. Header files must contain an include guard.

#ifndef COM_COMPANY_MODULE_CLASSNAME_H #define COM_COMPANY_MODULE_CLASSNAME_H : #endif

The 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.

#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. 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 must always be done explicitly. Never 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 or file scope (static) variables.

 

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].

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.

 

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.

 

53. 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 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 so common in C/C++ however that it can be used.

 

54. 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

55. 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.

 

56. Loop variables should be initialized immediately before the loop.

isDone = false; // NOT: bool isDone = false; while (!isDone) { // : : // while (!isDone) { } // : // }

 

 

57. 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.

 

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

 

These statements should only be used if they prove to give higher readability than their structured counterparts.

 

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.

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. 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 emphasize 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 emphasize 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 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.

 

69. 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.

 

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

 

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

6 Layout and Comments

6.1 Layout

71. Basic indentation should be 2.

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, and 2 chosen to reduce the chance of splitting code lines.

 

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(); }

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. 

 

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 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.

 

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 statments.

 

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 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 statments 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 enhanbces 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.

 

93. Comments should be included relative to their position in the code. [1]

while (true) { // NOT: while (true) { // Do something // Do something something(); something(); } }

This is to avoid that the comments break the logical structure of the program.

 

94. 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 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%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