From e9f3990ad795d2fee2a18e4efb0b8ccf950df056 Mon Sep 17 00:00:00 2001 From: Anthony Thibault Date: Fri, 29 Mar 2019 15:36:21 -0700 Subject: [PATCH] Added section numbers back to document --- CODING_STANDARD.md | 378 ++++++++++++++++++++++++--------------------- 1 file changed, 199 insertions(+), 179 deletions(-) diff --git a/CODING_STANDARD.md b/CODING_STANDARD.md index 5e990c7988..010d57a99c 100644 --- a/CODING_STANDARD.md +++ b/CODING_STANDARD.md @@ -6,105 +6,106 @@ Note that the current code base does not necessarily follow this with 100% consi Basically taken directly from [http://geosoft.no/development/cppstyle.html](http://geosoft.no/development/cppstyle.html) with some subtle changes and omissions. -## Naming +## 1. Naming -### General Naming Conventions +### 1.1. General Naming Conventions -#### Names representing types must be in mixed case starting with upper case. +#### 1.1.1. Names representing types must be in mixed case starting with upper case. -``` +```cpp Coach, PenaltyBox ``` -#### Private class variables must be in mixed case prefixed with an underscore. +#### 1.1.2. Private class variables must be in mixed case prefixed with an underscore. -``` +```cpp _puck, _team ``` -#### Local variables must be in mixed case (and NOT prefixed with an underscore). +#### 1.1.3. Local variables must be in mixed case (and NOT prefixed with an underscore). -``` +```cpp redLine, icingFrequency ``` -#### Constants must be all uppercase using underscore to separate words. +#### 1.1.4. Constants must be all uppercase using underscore to separate words. -``` +```cpp MAX_RINK_LENGTH, COLOR_RED_LINE ``` -#### Methods or functions must be verbs and written in mixed case starting with lower case. +#### 1.1.5. Methods or functions must be verbs and written in mixed case starting with lower case. -``` +```cpp getPlayerNumber(), computeGoalsAgainstAverage() ``` -#### Names representing namespaces should be all lowercase. +#### 1.1.6. Names representing namespaces should be all lowercase. -``` +```cpp puck::geometry, ice::math ``` -#### Names representing template types should be a single uppercase letter. +#### 1.1.7. Names representing template types should be a single uppercase letter. -``` +```cpp template, template, template ``` This makes template names stand out relative to all other names used. -#### Abbreviations and acronyms must be uppercase when used in a name or lowercase when used at the beginning of a variable +#### 1.1.8. Abbreviations and acronyms must be uppercase when used in a name or lowercase when used at the beginning of a variable -``` +```cpp showNHLStandings(); // not showNhlStandings(); exportASCIIStanleyCup(); // not exportAsciiStanleyCup(); UDPSocket udpSocket; // not UDPSocket uDPSocket; ``` -#### Global variables should always be referred to using the :: operator. +#### 1.1.9. Global variables should always be referred to using the :: operator. -``` -::jumbotron.powerOn(), ::league.lockout(); +```cpp +::jumbotron.powerOn(); +::league.lockout(); ``` -#### Generic variables should have the same name as their type. +#### 1.1.10. Generic variables should have the same name as their type. -``` +```cpp void setPuckLogo(Logo* logo) // not void setPuckLogo(Logo* aLogo) ``` -These will be discernible from class private variables since they are not prefixed with an underscore. +These will be discernible from class member variables since they are not prefixed with an underscore. -#### All names should be written in English. +#### 1.1.11. All names should be written in English. -``` -hockeyStick; // NOT: bastonDeHockey +```cpp +int hockeyStick; // NOT: bastonDeHockey ``` -#### The name of the object is implicit, and should be avoided in a method name. +#### 1.1.12. The name of the object is implicit, and should be avoided in a method name. -``` +```cpp puck.getDensity(); // NOT: puck.getPuckDensity(); ``` -### Specific Naming Conventions +### 1.2 Specific Naming Conventions -#### The terms get/set must be used where an attribute is accessed directly. +#### 1.2.1. The terms get/set must be used where an attribute is accessed directly. -``` +```cpp player.getNumber(); player.setNumber(number); stick.getFlex(); @@ -114,15 +115,15 @@ stick.setFlex(flex); There is an exception for boolean getters. Naming for boolean attributes should follow [section 1.2.10](https://wiki.highfidelity.com/wiki/Coding_Standards#1-2-10-the-prefix-is-should-be-used-for-boolean-variables-and-methods-). The getter for a boolean attribute does not need to be prefixed with 'get', and should simply match the name of the boolean attribute. The following example is for a member variable `_isCaptain` on the `crosby` object. -``` +```cpp crosby.setIsCaptain(true); crosby.isCaptain(); ``` -#### The term compute can be used in methods where something is computed. +#### 1.2.2. The term compute can be used in methods where something is computed. -``` +```cpp team->computePowerPlayPercentage(); player->computePointsPerGame(); @@ -130,9 +131,9 @@ player->computePointsPerGame(); Give the reader the immediate clue that this is a potentially time-consuming operation, and if used repeatedly, she might consider caching the result. Consistent use of the term enhances readability. -#### The term find can be used in methods where something is looked up. +#### 1.2.3. The term find can be used in methods where something is looked up. -``` +```cpp net.findGoalLinePosition(); team.findHeaviestPlayer(); @@ -140,7 +141,7 @@ team.findHeaviestPlayer(); Give the reader the immediate clue that this is a simple look up method with a minimum of computations involved. Consistent use of the term enhances readability. -#### The term initialize can be used where an object or a concept is established. +#### 1.2.4. The term initialize can be used where an object or a concept is established. ``` rink.initializePaintedLines(); @@ -148,65 +149,65 @@ video.initializeOnScreenScore(); ``` -#### Variables representing GUI components should be suffixed by the component type name. +#### 1.2.5. Variables representing GUI components should be suffixed by the component type name. -``` +```cpp scoreboardText, mainWindow, fileMenu ``` -#### Plural form should be used on names representing a collection of objects. +#### 1.2.6. Plural form should be used on names representing a collection of objects. -``` -vector players; +```cpp +std::vector players; float savePercentages[]; ``` -#### The prefix num should be used for variables representing a number of objects. +#### 1.2.7. The prefix num should be used for variables representing a number of objects. -``` +```cpp numGoals, numAssists ``` -#### The suffix Num should be used for variables representing an entity number. +#### 1.2.8. The suffix Num should be used for variables representing an entity number. -``` +```cpp playerNum, teamNum ``` -#### Iterator variables should be called i, j, k etc. +#### 1.2.9. Iterator variables should be called i, j, k etc. -``` +```cpp for (int i = 0; i < numGoals); i++) { goals[i].playVideo(); } ``` -#### The prefix is should be used for boolean variables and methods. +#### 1.2.10. The prefix is should be used for boolean variables and methods. isGoodGoal, isRetired, isWinningTeam Occasionally the has, can, should, and want prefixes will be better choices. *Note: "want" should generally be used for optional items that are specified by some third party action, e.g. command line or menu options that enable additional functionality, or protocol versioning where negotiation occurs between client and server.* -``` +```cpp hasWonStanleyCup, canPlay, shouldPass, wantDebugLogging ``` -#### Complement names must be used for complement operations +#### 1.2.11. Complement names must be used for complement operations -``` +```cpp get/set, add/remove, create/destroy, start/stop ``` -#### Abbreviations in names should be avoided. +#### 1.2.12. Abbreviations in names should be avoided. -``` +```cpp computeGoalsAgainstAverage(); // NOT: compGlsAgstAvg(); ``` @@ -215,27 +216,27 @@ There are domain specific phrases that are more naturally known through their ab Use `html` instead of `hypertextMarkupLanguage`. -#### Naming pointers specifically should be avoided. +#### 1.2.13. Naming pointers specifically should be avoided. -``` +```cpp Puck* puck; // NOT: Puck * puckPtr; ``` 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. -#### Negated boolean variable names must be avoided. +#### 1.2.14. Negated boolean variable names must be avoided. -``` +```cpp bool isRetired; // NOT: isNotRetired or isNotPlaying ``` This is done to avoid double negatives when used in conjunction with the logical negation operator. -#### Enumeration constants can be prefixed by a common type name. +#### 1.2.15. Enumeration constants can be prefixed by a common type name. -``` +```cpp enum Jersey { JERSEY_HOME, JERSEY_AWAY, @@ -244,31 +245,31 @@ enum Jersey { ``` -#### Exception classes should be suffixed with Exception. +#### 1.2.15. Exception classes should be suffixed with Exception. -``` +```cpp class GoalException { ... }; ``` -## Files +## 2. Files -### Source Files +### 2.1 Source Files -#### C++ header files should have the extension .h. Source files should have the extension .cpp. +#### 2.1.1. C++ header files should have the extension .h. Source files should have the extension .cpp. -``` +```cpp Puck.h, Puck.cpp ``` -#### A class should always be declared in a header file and defined in a source file where the name of the files match the name of the class. +#### 2.1.2. A class should always be declared in a header file and defined in a source file where the name of the files match the name of the class. `class Puck` defined in `Puck.h`, `Puck.cpp` -#### Most function implementations should reside in the source file. +#### 2.1.3. Most function implementations should reside in the source file. 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. @@ -277,7 +278,7 @@ The header files should declare an interface, the source file should implement i - Methods that will be called multiple times in tight-loops or other high-performance situations and must be high performance can be included in the header file BELOW the class definition marked as inline. - All other methods must be in a cpp file. -``` +```cpp class Puck { public: // simple getters/setters should appear in the header file @@ -303,15 +304,15 @@ inline void Puck::doSomethingHighPerformance() const { ``` -#### File content must be kept within 128 columns. +#### 2.1.4. File content must be kept within 128 columns. -#### Special characters like TAB and page break must be avoided. +#### 2.1.5. Special characters like TAB and page break must be avoided. Use four spaces for indentation. -#### The incompleteness of split lines must be made obvious. +#### 2.1.6. The incompleteness of split lines must be made obvious. -``` +```cpp teamGoals = iginlaGoals + crosbyGoals + malkinGoals; @@ -332,13 +333,13 @@ Split lines occurs when a statement exceed the 128 column limit given above. It In general: Break after a comma. Break after an operator. Align the new line with the beginning of the expression on the previous line. -### Include Files and Include Statements +### 2.2. Include Files and Include Statements -#### Header files must contain an include guard. +#### 2.2.1. Header files must contain an include guard. Include guards should be in the following format: hifi_$BASENAME_h. -``` +```cpp #ifndef hifi_SharedUtil_h #define hifi_SharedUtil_h @@ -348,9 +349,9 @@ Include guards should be in the following format: hifi_$BASENAME_h. ``` -#### 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. +#### 2.2.2. 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. -``` +```cpp #include #include @@ -362,21 +363,21 @@ Include guards should be in the following format: hifi_$BASENAME_h. ``` -#### Include statements must be located at the top of a file only. +#### 2.2.3. Include statements must be located at the top of a file only. -## Statements +## 3. Statements -### Types +### 3.1. Types -#### The parts of a class must be sorted public, protected and private. All sections must be identified explicitly. Not applicable sections should be left out. +#### 3.1.1. The parts of a class must be sorted public, protected and private. 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. -#### Never rely on implicit type conversion. // NOT: floatValue = intValue; +#### 3.1.2. Never rely on implicit type conversion. // NOT: floatValue = intValue; -##### Primitive types should use C style casting: +##### 3.1.2.1. Primitive types should use C style casting: -``` +```cpp int foo = 1; float bar = (float)foo; // NOT this: float fubar = float(foo); @@ -385,9 +386,9 @@ uint8_t* barDataAt = (uint8_t*)&bar; // pointers to primitive types also use C s ``` -##### Class pointers must use C++ style casting: +##### 3.1.2.2. Class pointers must use C++ style casting: -``` +```cpp Player* player = getPlayer("forward"); Forward* forward = static_cast(player); @@ -395,19 +396,19 @@ Forward* forward = static_cast(player); For more info about C++ type casting: [http://stackoverflow.com/questions/1609163/what-is-the-difference-between-static-cast-and-c-style-casting](http://stackoverflow.com/questions/1609163/what-is-the-difference-between-static-cast-and-c-style-casting) -#### Use of *const* +#### 3.1.3. Use of *const* -##### Use const types for variables, parameters, return types, and methods whenever possible +##### 3.1.3.1. Use const types for variables, parameters, return types, and methods whenever possible -``` +```cpp void exampleBarAndFoo(const Bar& bar, const char* foo); // doesn't modify bar and foo, use const types void ClassBar::spam() const { } // doesn't modify instance of ClassBar, use const method ``` -##### Place the const keyword before the type +##### 3.1.3.2. Place the const keyword before the type -``` +```cpp void foo(const Bar& bar); // NOT: void foo(Bar const& bar); void spam(const Foo* foo); @@ -415,19 +416,19 @@ void spam(const Foo* foo); ``` -##### When implementing a getter for a class that returns a class member that is a complex data type, return a const& to that member. +##### 3.1.3.3. When implementing a getter for a class that returns a class member that is a complex data type, return a const& to that member. -``` +```cpp const glm::vec3& AABox::getCorner() const; // NOT: glm::vec3 AABox::getCorner() const; ``` -#### Type aliases +#### 3.1.4. Type aliases -##### When creating a type alias, prefer the using keyword. +##### 3.1.4.1. When creating a type alias, prefer the using keyword. -``` +```cpp template using Vec = std::vector>; using Nodes = Vec ; @@ -435,15 +436,15 @@ using Nodes = Vec ; ``` -### Variables +### 3.2. Variables -#### Variables should be initialized where they are declared. +#### 3.2.1. 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: -``` +```cpp Player crosby, dupuis, kunitz; getLineStats(&crosby, &dupuis, &kunitz); @@ -451,11 +452,11 @@ getLineStats(&crosby, &dupuis, &kunitz); In these cases it should be left uninitialized rather than initialized to some phony value. -#### Initialization of member variables with default values +#### 3.2.2. Initialization of member variables with default values When possible, initialization of default values for class members should be included in the header file where the member variable is declared, as opposed to the constructor. Use the Universal Initializer format (brace initialization) rather than the assignment operator (equals). -``` +```cpp private: float _goalsPerGame { 0.0f }; // NOT float _goalsPerGame = 0.0f; @@ -463,7 +464,7 @@ private: However, brace initialization should be used with care when using container types that accept an initializer list as a constructor parameters. For instance, -``` +```cpp std::vector _foo { 4, 100 } ``` @@ -472,11 +473,11 @@ Might refer to `std::vector::vector(std::initializer_list)` or it might Classes that are forward declared and only known to the implementation may be initialized to a default value in the constructor initialization list. -#### Use of global variables should be minimized +#### 3.2.3. Use of global variables should be minimized [http://stackoverflow.com/questions/484635/are-global-variables-bad](http://stackoverflow.com/questions/484635/are-global-variables-bad) -#### Class variables should never be declared public +#### 3.2.4. Class variables should never be declared public Use private variables and access functions instead. @@ -484,9 +485,9 @@ One exception to this rule is when the class is essentially a data structure, wi *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.* -#### C++ pointers and references should have their reference symbol next to the type rather than to the name. +#### 3.2.5. C++ pointers and references should have their reference symbol next to the type rather than to the name. -``` +```cpp float* savePercentages; // NOT: float *savePercentages; or float * savePercentages; @@ -497,9 +498,9 @@ void checkCups(int& numCups); The pointer-ness or reference-ness of a variable is a property of the type rather than the name. Also see [rule 3.1.3.2](https://wiki.highfidelity.com/wiki/Coding_Standards#constplacement) regarding placement the const keyword before the type. -#### Implicit test for 0 should not be used other than for boolean variables or non-NULL pointers. +#### 3.2.6. Implicit test for 0 should not be used other than for boolean variables or non-NULL pointers. -``` +```cpp if (numGoals != 0) // NOT: if (numGoals) if (savePercentage != 0.0) // NOT: if (savePercentage) @@ -514,17 +515,17 @@ if (!childNode) It is not necessarily defined by the C++ standard that ints and floats 0 are implemented as binary 0. -#### Variables should be declared in the smallest scope possible. +#### 3.2.7. 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. -### Loops +### 3.3. Loops -#### Loop variables should be initialized immediately before the loop. +#### 3.3.1. Loop variables should be initialized immediately before the loop. -#### The form while (true) should be used for infinite loops. +#### 3.3.2. The form while (true) should be used for infinite loops. -``` +```cpp while (true) { : } @@ -541,11 +542,11 @@ while (1) { ``` -### Conditionals +### 3.4. Conditionals -#### The nominal case should be put in the if-part and the exception in the else-part of an if statement +#### 3.4.1. The nominal case should be put in the if-part and the exception in the else-part of an if statement -``` +```cpp bool isGoal = pastGoalLine(position); if (isGoal) { @@ -558,9 +559,9 @@ if (isGoal) { Makes sure that the exceptions don't obscure the normal path of execution. This is important for both the readability and performance. -#### The conditional should be put on a separate line and wrapped in braces. +#### 3.4.2. The conditional should be put on a separate line and wrapped in braces. -``` +```cpp if (isGoal) { lightTheLamp(); } @@ -569,9 +570,9 @@ if (isGoal) { ``` -#### Write the expression of a conditional similar to how you would speak it out loud. +#### 3.4.3. Write the expression of a conditional similar to how you would speak it out loud. -``` +```cpp if (someVariable == 0) { doSomething(); } @@ -579,19 +580,19 @@ if (someVariable == 0) { ``` -### Miscellaneous +### 3.5. Miscellaneous -#### Constants and Magic Numbers +#### 3.5.1. Constants and Magic Numbers -#### The use of magic numbers in the code should be avoided. +##### 3.5.1.1. 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. -##### Declare constants closest to the scope of their use. +##### 3.5.1.2. Declare constants closest to the scope of their use. -``` +```cpp bool checkValueLimit(int value) { const int ValueLimit = 10; // I only use this constant here, define it here in context return (value > ValueLimit); @@ -599,17 +600,17 @@ bool checkValueLimit(int value) { ``` -##### Use const typed variables instead of #define +##### 3.5.1.3. Use const typed variables instead of #define -``` +```cpp const float LARGEST_VALUE = 10000.0f; // NOT: #define LARGEST_VALUE 10000.0f ``` -#### Floating point constants should always be written with decimal point and at least one decimal. +#### 3.5.2. Floating point constants should always be written with decimal point and at least one decimal. -``` +```cpp double stickLength = 0.0; // NOT: double stickLength = 0; double penaltyMinutes; @@ -618,36 +619,36 @@ penaltyMinutes = (minor + misconduct) * 2.0; ``` -#### Floating point constants should always be written with a digit before the decimal point. +#### 3.5.3. Floating point constants should always be written with a digit before the decimal point. -``` +```cpp double penaltyMinutes = 0.5; // NOT: double penaltyMinutes = .5; ``` -#### When using a single precision float type, include the trailing f. +#### 3.5.4. When using a single precision float type, include the trailing f. -``` +```cpp float penaltyMinutes = 0.5f; // NOT: float penaltyMinutes = 0.5; ``` -## Layout and Comments +## 4. Layout and Comments -### Layout +### 4.1. Layout -#### Basic indentation should be 4. +#### 4.1.1. Basic indentation should be 4. -``` +```cpp if (player.isCaptain) { player.yellAtReferee(); } ``` -#### Use inline braces for block layout +#### 4.1.2. Use inline braces for block layout -``` +```cpp while (!puckHeld) { lookForRebound(); } @@ -660,9 +661,9 @@ while (!puckHeld) { ``` -#### The class declarations should have the following form: +#### 4.1.3. The class declarations should have the following form: -``` +```cpp class GoalieStick : public HockeyStick { public: ... @@ -674,18 +675,18 @@ private: ``` -#### Method definitions should have the following form: +#### 4.1.4. Method definitions should have the following form: -``` +```cpp void goalCelebration() { ... } ``` -#### The if-else class of statements should have the following form: +#### 4.1.5. The if-else class of statements should have the following form: -``` +```cpp if (isScorer) { scoreGoal(); } @@ -706,34 +707,34 @@ if (isScorer) { ``` -#### A for statement should have the following form: +#### 4.1.6. A for statement should have the following form: -``` +```cpp for (int i = 0; i < GRETZKY_NUMBER; i++) { getActivePlayerWithNumber(i); } ``` -#### A while statement should have the following form: +#### 4.1.7. A while statement should have the following form: -``` +```cpp while (!whistle) { keepPlaying(); } ``` -#### A do-while statement should have the following form: +#### 4.1.8. A do-while statement should have the following form: -``` +```cpp do { skate(); } while (!tired); ``` -#### Switch/Case Statements: +#### 4.1.9. Switch/Case Statements: A switch statements should follow the following basic formatting rules: @@ -745,7 +746,7 @@ A switch statements should follow the following basic formatting rules: Examples of acceptable form are: -``` +```cpp switch (foo) { case BAR: doBar(); @@ -783,9 +784,9 @@ switch (jerseyNumber) { ``` -#### A try-catch statement should have the following form: +#### 4.1.10. A try-catch statement should have the following form: -``` +```cpp try { tradePlayer(); } catch (const NoTradeClauseException& exception) { @@ -794,13 +795,24 @@ try { ``` -#### Single statement if-else, for or while statements must be written with brackets. +#### 4.1.11. Single statement if-else, for or while statements must be written with braces. + +```cpp +// GOOD: +for (int i = 0; i < numItems; i++) { + item[i].manipulate(); +} + +// BAD: braces are missing +for (int i = 0; i < numItems; i++) + item[i].manipulate(); +``` ### 4.2 White space -#### Conventional operators should be surrounded by a space character, except in cases like mathematical expressions where it is easier to visually parse when spaces are used to enhance the grouping. +#### 4.2.1 Conventional operators should be surrounded by a space character, except in cases like mathematical expressions where it is easier to visually parse when spaces are used to enhance the grouping. -``` +```cpp potential = (age + skill) * injuryChance; // NOT: potential = (age+skill)*injuryChance; @@ -816,38 +828,46 @@ v = w * (x + z); ``` -#### C++ reserved words should be followed by a white space.Commas should be followed by a white space. +#### 4.2.2. C++ reserved words should be followed by a white space.Commas should be followed by a white space. -``` +```cpp setLine(leftWing, center, rightWing, leftDefense, rightDefense); // NOT: setLine(leftWing,center,rightWing,leftDefense,rightDefense); ``` -#### Semicolons in for statments should be followed by a space character. +#### 4.2.3. Commas should be followed by a white space. +```cpp +setLine(leftWing, center, rightWing, leftDefense, rightDefense); +// NOT: setLine(leftWing,center,rightWing,leftDefense,rightDefense); ``` + + +#### 4.2.4. Semicolons in for statments should be followed by a space character. + +```cpp for (i = 0; i < 10; i++) { // NOT: for(i=0;i<10;i++){ ``` -#### Declaring and Calling Functions +#### 4.2.5. Declaring and Calling Functions - Function names should not be followed by a white space. - And there should be no space between the open parenthesis and the first parameter, and no space between the last parameter and the close parenthesis. Examples: -``` +```cpp setCaptain(ovechkin); // NOT: setCaptain (ovechkin); // NOT: doSomething( int foo, float bar ); ``` -#### Logical units within a block should be separated by one blank line. +#### 4.2.6. Logical units within a block should be separated by one blank line. -``` +```cpp Team penguins = new Team(); Player crosby = new Player(); @@ -860,7 +880,7 @@ penguins.hireCoach(); ``` -#### Avoid adding optional spaces across multi-line statements and adjacent statements. +#### 4.2.7. Avoid adding optional spaces across multi-line statements and adjacent statements. Avoid the following: @@ -876,7 +896,7 @@ charaSlapShotSpeed = computeShot(stickFlex, weber); A change to the length of a variable in these sections causes unnecessary changes to the other lines. -#### Multi-line statements must have all n+1 lines indented at least one level (four spaces). +#### 4.2.8. Multi-line statements must have all n+1 lines indented at least one level (four spaces). Align all n+2 lines with the indentation of the n+1 line. @@ -932,15 +952,15 @@ aCPlusPlusFunctionOfTwoLambdas([](gpu::Batch& batch) { ### 4.3 Comments -#### All comments should be written in English +#### 4.3.1. All comments should be written in English In an international environment English is the preferred language. -#### Use // for all comments, including multi-line comments. +#### 4.3.2. Use // for all comments, including multi-line comments. -An exception to this rule applies for Doxygen comments where there are three slashes. +An exception to this rule applies for jsdoc or Doxygen comments. -``` +```cpp // Comment spanning // more than one line. @@ -948,9 +968,9 @@ An exception to this rule applies for Doxygen comments where there are three sla There should be a space between the "//" and the actual comment -#### Comments should be included relative to their position in the code +#### 4.3.3. Comments should be included relative to their position in the code -``` +```cpp while (true) { // crosby is always injured crosbyInjury(); @@ -964,11 +984,11 @@ while (true) { ``` -#### Source files (header and implementation) must include a boilerplate. +#### 4.3.4. Source files (header and implementation) must include a boilerplate. Boilerplates should include the filename, location, creator, copyright, and Apache 2.0 License information and be placed at the top of the file. -``` +```cpp // // NodeList.h // libraries/shared/src @@ -984,11 +1004,11 @@ Boilerplates should include the filename, location, creator, copyright, and Apac ``` -#### Never include Horizontal "line break" style comment blocks +#### 4.3.5. Never include Horizontal "line break" style comment blocks These types of comments are explicitly not allowed. If you need to break up sections of code, just leave an extra blank line. -``` +```cpp ////////////////////////////////////////////////////////////////////////////////// /********************************************************************************/