From 656051a6e05cf3b5d096a66949c4a35ca1f6e85a Mon Sep 17 00:00:00 2001 From: Anthony Thibault Date: Tue, 26 Feb 2019 12:03:57 -0800 Subject: [PATCH 1/7] Added coding standard doc to project --- CODING_STANDARD.md | 998 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 998 insertions(+) create mode 100644 CODING_STANDARD.md diff --git a/CODING_STANDARD.md b/CODING_STANDARD.md new file mode 100644 index 0000000000..5e990c7988 --- /dev/null +++ b/CODING_STANDARD.md @@ -0,0 +1,998 @@ +--- +title: 'Coding Standards' +--- + +Note that the current code base does not necessarily follow this with 100% consistency. It will be an ongoing process to try and sanitize the existing code to match these guidelines. + +Basically taken directly from [http://geosoft.no/development/cppstyle.html](http://geosoft.no/development/cppstyle.html) with some subtle changes and omissions. + +## Naming + +### General Naming Conventions + +#### Names representing types must be in mixed case starting with upper case. + +``` +Coach, PenaltyBox + +``` + +#### Private class variables must be in mixed case prefixed with an underscore. + +``` +_puck, _team + +``` + +#### Local variables must be in mixed case (and NOT prefixed with an underscore). + +``` +redLine, icingFrequency + +``` + +#### Constants must be all uppercase using underscore to separate words. + +``` +MAX_RINK_LENGTH, COLOR_RED_LINE + +``` + +#### Methods or functions must be verbs and written in mixed case starting with lower case. + +``` +getPlayerNumber(), computeGoalsAgainstAverage() + +``` + +#### Names representing namespaces should be all lowercase. + +``` +puck::geometry, ice::math + +``` + +#### Names representing template types should be a single uppercase letter. + +``` +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 + +``` +showNHLStandings(); // not showNhlStandings(); +exportASCIIStanleyCup(); // not exportAsciiStanleyCup(); +UDPSocket udpSocket; // not UDPSocket uDPSocket; + +``` + +#### Global variables should always be referred to using the :: operator. + +``` +::jumbotron.powerOn(), ::league.lockout(); + +``` + +#### Generic variables should have the same name as their type. + +``` +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. + +#### All names should be written in English. + +``` +hockeyStick; // NOT: bastonDeHockey + +``` + +#### The name of the object is implicit, and should be avoided in a method name. + +``` +puck.getDensity(); // NOT: puck.getPuckDensity(); + +``` + +### Specific Naming Conventions + +#### The terms get/set must be used where an attribute is accessed directly. + +``` +player.getNumber(); +player.setNumber(number); +stick.getFlex(); +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. + +``` +crosby.setIsCaptain(true); +crosby.isCaptain(); + +``` + +#### The term compute can be used in methods where something is computed. + +``` +team->computePowerPlayPercentage(); +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. + +``` +net.findGoalLinePosition(); +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. + +``` +rink.initializePaintedLines(); +video.initializeOnScreenScore(); + +``` + +#### Variables representing GUI components should be suffixed by the component type name. + +``` +scoreboardText, mainWindow, fileMenu + +``` + +#### Plural form should be used on names representing a collection of objects. + +``` +vector players; +float savePercentages[]; + +``` + +#### The prefix num should be used for variables representing a number of objects. + +``` +numGoals, numAssists + +``` + +#### The suffix Num should be used for variables representing an entity number. + +``` +playerNum, teamNum + +``` + +#### Iterator variables should be called i, j, k etc. + +``` +for (int i = 0; i < numGoals); i++) { + goals[i].playVideo(); +} + +``` + +#### 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.* + +``` +hasWonStanleyCup, canPlay, shouldPass, wantDebugLogging + +``` + +#### Complement names must be used for complement operations + +``` +get/set, add/remove, create/destroy, start/stop + +``` + +#### Abbreviations in names should be avoided. + +``` +computeGoalsAgainstAverage(); // NOT: compGlsAgstAvg(); + +``` + +There are domain specific phrases that are more naturally known through their abbreviations/acronym. These phrases should be kept abbreviated. + +Use `html` instead of `hypertextMarkupLanguage`. + +#### Naming pointers specifically should be avoided. + +``` +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. + +``` +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. + +``` +enum Jersey { + JERSEY_HOME, + JERSEY_AWAY, + JERSEY_ALTERNATE +}; + +``` + +#### Exception classes should be suffixed with Exception. + +``` +class GoalException { + ... +}; + +``` + +## Files + +### Source Files + +#### C++ header files should have the extension .h. Source files should have the extension .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. + +`class Puck` defined in `Puck.h`, `Puck.cpp` + +#### 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. + +- Simple getters and setters that just access private member variables should appear inline in the class definition in the header file. +- Simple methods like those making slight mutations (that can fit on the same line in the definition and don't require additional includes in the header file) can be inlined in the class definition. +- 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. + +``` +class Puck { +public: + // simple getters/setters should appear in the header file + int getRadius() const { return _radius; } + void setRadius(int radius) { _radius = radius; } + + // Allowed, ok to include this simple mutation in line + void addBlaToList(Blah* bla) { _blas.append(bla); } + + // Allowed, because this is a simple method + int calculateCircumference () { return PI * pow(_radius, 2.0); } + + // this routine needs to be fast, we'll inline it below + void doSomethingHighPerformance() const; + ... +private: + int _radius; +} + +inline void Puck::doSomethingHighPerformance() const { + ... +} + +``` + +#### File content must be kept within 128 columns. + +#### Special characters like TAB and page break must be avoided. + +Use four spaces for indentation. + +#### The incompleteness of split lines must be made obvious. + +``` +teamGoals = iginlaGoals + crosbyGoals + + malkinGoals; + +addToScoreSheet(scorer, directAssister, + indirectAssister); + +setHeadline("Crosby scores 4" + " to force game 7."); + +for (int teamNum = 0; teamNum < numTeams; + teamNum++) { + ... +} + +``` + +Split lines occurs when a statement exceed the 128 column limit given above. It is difficult to provide 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. + +### Include Files and Include Statements + +#### Header files must contain an include guard. + +Include guards should be in the following format: hifi_$BASENAME_h. + +``` +#ifndef hifi_SharedUtil_h +#define hifi_SharedUtil_h + +... + +#endif // hifi_SharedUtil_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. + +``` +#include +#include + +#include +#include + +#include "Puck.h" +#include "PenaltyBox.h" + +``` + +#### Include statements must be located at the top of a file only. + +## Statements + +### 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. + +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; + +##### Primitive types should use C style casting: + +``` +int foo = 1; +float bar = (float)foo; +// NOT this: float fubar = float(foo); + +uint8_t* barDataAt = (uint8_t*)&bar; // pointers to primitive types also use C style casting. + +``` + +##### Class pointers must use C++ style casting: + +``` +Player* player = getPlayer("forward"); +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* + +##### Use const types for variables, parameters, return types, and methods whenever possible + +``` +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 + +``` +void foo(const Bar& bar); +// NOT: void foo(Bar const& bar); +void spam(const Foo* foo); +// NOT: void foo(Foo const* 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. + +``` +const glm::vec3& AABox::getCorner() const; +// NOT: glm::vec3 AABox::getCorner() const; + +``` + +#### Type aliases + +##### When creating a type alias, prefer the using keyword. + +``` +template +using Vec = std::vector>; +using Nodes = Vec ; +// NOT: typedef std::vector Nodes; + +``` + +### Variables + +#### 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: + +``` +Player crosby, dupuis, kunitz; +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 + +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). + +``` +private: + float _goalsPerGame { 0.0f }; // NOT float _goalsPerGame = 0.0f; + +``` + +However, brace initialization should be used with care when using container types that accept an initializer list as a constructor parameters. For instance, + +``` +std::vector _foo { 4, 100 } + +``` + +Might refer to `std::vector::vector(std::initializer_list)` or it might refer to `std::vector (size_type n, const T& val = value_type())`. Although the rules of precedence dictate that it will resolve to one of these, it's not immediately obvious to other developers which it is, so avoid such ambiguities. + +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 + +[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 + +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. + +*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. + +``` +float* savePercentages; +// NOT: float *savePercentages; or float * savePercentages; + +void checkCups(int& numCups); +// NOT: int &numCups or 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. + +``` +if (numGoals != 0) // NOT: if (numGoals) +if (savePercentage != 0.0) // NOT: if (savePercentage) + +// Testing pointers for non-NULL is prefered, e.g. where +// childNode is Node* and you’re testing for non NULL +if (childNode) + +// Testing for null is also preferred +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. + +Keeping the operations on a variable within a small scope, it is easier to control the effects and side effects of the variable. + +### Loops + +#### Loop variables should be initialized immediately before the loop. + +#### The form while (true) should be used for infinite loops. + +``` +while (true) { + : +} + +// NOT: + +for (;;) { + : +} + +while (1) { + : +} + +``` + +### Conditionals + +#### The nominal case should be put in the if-part and the exception in the else-part of an if statement + +``` +bool isGoal = pastGoalLine(position); + +if (isGoal) { + ... +} else { + ... +} + +``` + +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. + +``` +if (isGoal) { + lightTheLamp(); +} + +// NOT: if (isGoal) lightTheLamp(); + +``` + +#### Write the expression of a conditional similar to how you would speak it out loud. + +``` +if (someVariable == 0) { + doSomething(); +} +// NOT: if (0 == someVariable) + +``` + +### Miscellaneous + +#### Constants and Magic Numbers + +#### 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. + +``` +bool checkValueLimit(int value) { + const int ValueLimit = 10; // I only use this constant here, define it here in context + return (value > ValueLimit); +} + +``` + +##### Use const typed variables instead of #define + +``` +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. + +``` +double stickLength = 0.0; // NOT: double stickLength = 0; + +double penaltyMinutes; +... +penaltyMinutes = (minor + misconduct) * 2.0; + +``` + +#### Floating point constants should always be written with a digit before the decimal point. + +``` +double penaltyMinutes = 0.5; // NOT: double penaltyMinutes = .5; + +``` + +#### When using a single precision float type, include the trailing f. + +``` +float penaltyMinutes = 0.5f; // NOT: float penaltyMinutes = 0.5; + +``` + +## Layout and Comments + +### Layout + +#### Basic indentation should be 4. + +``` +if (player.isCaptain) { + player.yellAtReferee(); +} + +``` + +#### Use inline braces for block layout + +``` +while (!puckHeld) { + lookForRebound(); +} + +// NOT: +// while (!puckHeld) +// { +// lookForRebound(); +// } + +``` + +#### The class declarations should have the following form: + +``` +class GoalieStick : public HockeyStick { +public: + ... +protected: + ... +private: + ... +}; + +``` + +#### Method definitions should have the following form: + +``` +void goalCelebration() { + ... +} + +``` + +#### The if-else class of statements should have the following form: + +``` +if (isScorer) { + scoreGoal(); +} + +if (isScorer) { + scoreGoal(); +} else { + saucerPass(); +} + +if (isScorer) { + scoreGoal(); +} else if (isPlaymaker) { + saucerPass(); +} else { + startFight(); +} + +``` + +#### A for statement should have the following form: + +``` +for (int i = 0; i < GRETZKY_NUMBER; i++) { + getActivePlayerWithNumber(i); +} + +``` + +#### A while statement should have the following form: + +``` +while (!whistle) { + keepPlaying(); +} + +``` + +#### A do-while statement should have the following form: + +``` +do { + skate(); +} while (!tired); + +``` + +#### Switch/Case Statements: + +A switch statements should follow the following basic formatting rules: + +- The case statements are indented one indent (4 spaces) from the switch. +- The code for each case should be indented one indent (4 spaces) from the case statement. +- Each separate case should have a break statement, unless it is explicitly intended for the case to fall through to the subsequent cases. In the event that a case statement executes some code, then falls through to the next case, you must include an explicit comment noting that this is intentional. +- Break statements should be aligned with the code of the case, e.g. indented 4 spaces from the case statement. +- In the event that brackets are required to create local scope, the open bracket should appear on the same line as the case, and the close bracket should appear on the line immediately following the break aligned with the case statement. + +Examples of acceptable form are: + +``` +switch (foo) { + case BAR: + doBar(); + break; + + // notice brackets below follow the standard bracket placement for other control structures + case SPAM: { + int spam = 0; + doSomethingElse(spam); + break; + } + + case SPAZZ: + case BAZZ: + doSomething(); + // fall through to next case + + case RAZZ: + default: + doSomethingElseEntirely(); + break; +} + +// or in cases where returns occur at each case, this form is also accpetable +switch (jerseyNumber) { + case 87: + return crosby; + case 66: + return lemieux; + case 99: + return gretzky; + default: + return NULL; +} + +``` + +#### A try-catch statement should have the following form: + +``` +try { + tradePlayer(); +} catch (const NoTradeClauseException& exception) { + negotiateNoTradeClause(); +} + +``` + +#### Single statement if-else, for or while statements must be written with brackets. + +### 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. + +``` +potential = (age + skill) * injuryChance; +// NOT: potential = (age+skill)*injuryChance; + +// Assignment operators always have spaces around them. +x = 0; + +// Other binary operators usually have spaces around them, but it's +// OK to remove spaces around factors. Parentheses should have no +// internal padding. +v = w * x + y / z; +v = w*x + y/z; +v = w * (x + z); + +``` + +#### C++ reserved words should be followed by a white space.Commas should be followed by a white space. + +``` +setLine(leftWing, center, rightWing, leftDefense, rightDefense); +// NOT: setLine(leftWing,center,rightWing,leftDefense,rightDefense); + +``` + +#### Semicolons in for statments should be followed by a space character. + +``` +for (i = 0; i < 10; i++) { // NOT: for(i=0;i<10;i++){ + +``` + +#### 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: + +``` +setCaptain(ovechkin); +// NOT: setCaptain (ovechkin); +// NOT: doSomething( int foo, float bar ); + +``` + +#### Logical units within a block should be separated by one blank line. + +``` +Team penguins = new Team(); + +Player crosby = new Player(); +Player fleury = new Player(); + +penguins.setCaptain(crosby); +penguins.setGoalie(fleury); + +penguins.hireCoach(); + +``` + +#### Avoid adding optional spaces across multi-line statements and adjacent statements. + +Avoid the following: + +``` +oddsToWin = (averageAge * veteranWeight) + + (numStarPlayers * starPlayerWeight) + + (goalieOverall * goalieWeight); + +theGreatOneSlapShotSpeed = computeShot(stickFlex, chara); +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). + +Align all n+2 lines with the indentation of the n+1 line. + +When the multiple lines are bound by parentheses (as in arguments to a function call), the prefered style has no whitespace after the opening parenthesis or before the closing parenthesis. The n+1 lines are generally indented to the column immediately after the opening parenthesis (following the style for split expressions in 2.1.6). + +When the multiple lines are bound by braces (as in C++ initializers or JavaScript object notation), the preferred style has a newline after the opening brace and newline before the closing brace. The final line should not end in a comma, and no line should begin with a comma. The closing brace should begin in the same colum as the line that has the opening brace (following the style for split control statements in 4.1). + +Expressions, including C++ initializers and JavaScript object notation literals, can be placed on a single line if they are not deeply nested and end well within the column limit (2.1.4). + +The following are all acceptable: + +``` +shootOnNet(puckVelocity, + playerStrength, + randomChance); + +shootOnNet(puckVelocty, + playerStrength, + randomChance); + +if (longBooleanThatHasToDoWithHockey + && anotherBooleanOnANewLine); + +isGoodGoal = playerSlapShotVelocity > 100 + ? true + : false; + +var foo = { + spam: 1.0, + bar: "bar", + complex: { + red: 1, + white: 'blue' + }, + blah: zed +}; + +aJavascriptFunctionOfTwoFunctions(function (entity) { + print(entity); + foo(entity, 3); +}, function (entity) { + print('in second function'); + bar(entity, 4); +}); + +aCPlusPlusFunctionOfTwoLambdas([](gpu::Batch& batch) { + batch.setFramebuffer(nullptr); +}, [this](int count, float amount) { + frob(count, amount); +}); + +``` + +### 4.3 Comments + +#### All comments should be written in English + +In an international environment English is the preferred language. + +#### Use // for all comments, including multi-line comments. + +An exception to this rule applies for Doxygen comments where there are three slashes. + +``` +// Comment spanning +// more than one line. + +``` + +There should be a space between the "//" and the actual comment + +#### Comments should be included relative to their position in the code + +``` +while (true) { + // crosby is always injured + crosbyInjury(); +} + +// NOT: +// crosby is always injured +while (true) { + crosbyInjury(); +} + +``` + +#### 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. + +``` +// +// NodeList.h +// libraries/shared/src +// +// Created by Stephen Birarda on 2/15/13. +// Copyright 2013 High Fidelity, Inc. +// +// This is where you could place an optional one line comment about the file. +// +// Distributed under the Apache License, Version 2.0. +// See the accompanying file LICENSE or http://www.apache.org/licenses/LICENSE-2.0.html +// + +``` + +#### 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. + +``` +////////////////////////////////////////////////////////////////////////////////// + +/********************************************************************************/ + +//-------------------------------------------------------------------------------- +``` + From 740b8dc6bd18dcf7dd20405317c512d026842c8c Mon Sep 17 00:00:00 2001 From: Anthony Thibault Date: Tue, 26 Feb 2019 12:05:32 -0800 Subject: [PATCH 2/7] Updated coding standard link --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4654c311cc..f9a54f1adc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,7 +16,7 @@ Contributing git checkout -b new_branch_name ``` 4. Code - * Follow the [coding standard](https://docs.highfidelity.com/build-guide/coding-standards) + * Follow the [coding standard](CODING_STANDARD.md) 5. Commit * Use [well formed commit messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 6. Update your branch From e9f3990ad795d2fee2a18e4efb0b8ccf950df056 Mon Sep 17 00:00:00 2001 From: Anthony Thibault Date: Fri, 29 Mar 2019 15:36:21 -0700 Subject: [PATCH 3/7] 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 ////////////////////////////////////////////////////////////////////////////////// /********************************************************************************/ From 63db7efe7fbb47851d4f0b01af4b02d100376cdd Mon Sep 17 00:00:00 2001 From: Anthony Thibault Date: Fri, 29 Mar 2019 15:39:19 -0700 Subject: [PATCH 4/7] Updated title --- CODING_STANDARD.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/CODING_STANDARD.md b/CODING_STANDARD.md index 010d57a99c..149b51b923 100644 --- a/CODING_STANDARD.md +++ b/CODING_STANDARD.md @@ -1,6 +1,4 @@ ---- -title: 'Coding Standards' ---- +# Coding Standards Note that the current code base does not necessarily follow this with 100% consistency. It will be an ongoing process to try and sanitize the existing code to match these guidelines. From 3d719654e769bcbc6edd4cafd6f7dd52a7275a5f Mon Sep 17 00:00:00 2001 From: Anthony Thibault Date: Fri, 29 Mar 2019 15:40:30 -0700 Subject: [PATCH 5/7] Testing header numbers --- CODING_STANDARD.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CODING_STANDARD.md b/CODING_STANDARD.md index 149b51b923..622d06c15a 100644 --- a/CODING_STANDARD.md +++ b/CODING_STANDARD.md @@ -4,25 +4,25 @@ 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. -## 1. Naming +## [1.] Naming -### 1.1. General Naming Conventions +### [1.1.] General Naming Conventions -#### 1.1.1. 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 ``` -#### 1.1.2. 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 ``` -#### 1.1.3. 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 From bc2802207ecaed5ecef9cb4151b2b57ebc959356 Mon Sep 17 00:00:00 2001 From: Anthony Thibault Date: Fri, 29 Mar 2019 15:49:49 -0700 Subject: [PATCH 6/7] Updated section numbers with [] --- CODING_STANDARD.md | 212 ++++++++++++++++++++++----------------------- 1 file changed, 106 insertions(+), 106 deletions(-) diff --git a/CODING_STANDARD.md b/CODING_STANDARD.md index 622d06c15a..9f58105914 100644 --- a/CODING_STANDARD.md +++ b/CODING_STANDARD.md @@ -4,18 +4,18 @@ 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. -## [1.] Naming +## [1] Naming -### [1.1.] General Naming Conventions +### [1.1] General Naming Conventions -#### [1.1.1.] 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 ``` -#### [1.1.2.] 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 @@ -29,28 +29,28 @@ redLine, icingFrequency ``` -#### 1.1.4. 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 ``` -#### 1.1.5. 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() ``` -#### 1.1.6. Names representing namespaces should be all lowercase. +#### [1.1.6] Names representing namespaces should be all lowercase. ```cpp puck::geometry, ice::math ``` -#### 1.1.7. 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 @@ -59,7 +59,7 @@ template, template, template This makes template names stand out relative to all other names used. -#### 1.1.8. 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(); @@ -68,7 +68,7 @@ UDPSocket udpSocket; // not UDPSocket uDPSocket; ``` -#### 1.1.9. Global variables should always be referred to using the :: operator. +#### [1.1.9] Global variables should always be referred to using the :: operator. ```cpp ::jumbotron.powerOn(); @@ -76,7 +76,7 @@ UDPSocket udpSocket; // not UDPSocket uDPSocket; ``` -#### 1.1.10. 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) @@ -85,23 +85,23 @@ void setPuckLogo(Logo* logo) // not void setPuckLogo(Logo* aLogo) These will be discernible from class member variables since they are not prefixed with an underscore. -#### 1.1.11. All names should be written in English. +#### [1.1.11] All names should be written in English. ```cpp int hockeyStick; // NOT: bastonDeHockey ``` -#### 1.1.12. 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(); ``` -### 1.2 Specific Naming Conventions +### [1.2] Specific Naming Conventions -#### 1.2.1. 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(); @@ -119,7 +119,7 @@ crosby.isCaptain(); ``` -#### 1.2.2. 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(); @@ -129,7 +129,7 @@ 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. -#### 1.2.3. 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(); @@ -139,7 +139,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. -#### 1.2.4. 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(); @@ -147,14 +147,14 @@ video.initializeOnScreenScore(); ``` -#### 1.2.5. 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 ``` -#### 1.2.6. 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. ```cpp std::vector players; @@ -162,21 +162,21 @@ float savePercentages[]; ``` -#### 1.2.7. 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 ``` -#### 1.2.8. 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 ``` -#### 1.2.9. 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++) { @@ -185,7 +185,7 @@ for (int i = 0; i < numGoals); i++) { ``` -#### 1.2.10. 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. @@ -196,14 +196,14 @@ hasWonStanleyCup, canPlay, shouldPass, wantDebugLogging ``` -#### 1.2.11. 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 ``` -#### 1.2.12. Abbreviations in names should be avoided. +#### [1.2.12] Abbreviations in names should be avoided. ```cpp computeGoalsAgainstAverage(); // NOT: compGlsAgstAvg(); @@ -214,7 +214,7 @@ There are domain specific phrases that are more naturally known through their ab Use `html` instead of `hypertextMarkupLanguage`. -#### 1.2.13. Naming pointers specifically should be avoided. +#### [1.2.13] Naming pointers specifically should be avoided. ```cpp Puck* puck; // NOT: Puck * puckPtr; @@ -223,7 +223,7 @@ 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. -#### 1.2.14. Negated boolean variable names must be avoided. +#### [1.2.14] Negated boolean variable names must be avoided. ```cpp bool isRetired; // NOT: isNotRetired or isNotPlaying @@ -232,7 +232,7 @@ bool isRetired; // NOT: isNotRetired or isNotPlaying This is done to avoid double negatives when used in conjunction with the logical negation operator. -#### 1.2.15. 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 { @@ -243,7 +243,7 @@ enum Jersey { ``` -#### 1.2.15. Exception classes should be suffixed with Exception. +#### [1.2.16] Exception classes should be suffixed with Exception. ```cpp class GoalException { @@ -252,22 +252,22 @@ class GoalException { ``` -## 2. Files +## [2] Files -### 2.1 Source Files +### [2.1] Source Files -#### 2.1.1. 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 ``` -#### 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. +#### [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` -#### 2.1.3. 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. @@ -302,13 +302,13 @@ inline void Puck::doSomethingHighPerformance() const { ``` -#### 2.1.4. File content must be kept within 128 columns. +#### [2.1.4] File content must be kept within 128 columns. -#### 2.1.5. 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. -#### 2.1.6. 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 + @@ -331,9 +331,9 @@ 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. -### 2.2. Include Files and Include Statements +### [2.2] Include Files and Include Statements -#### 2.2.1. 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. @@ -347,7 +347,7 @@ Include guards should be in the following format: hifi_$BASENAME_h. ``` -#### 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. +#### [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 @@ -361,19 +361,19 @@ Include guards should be in the following format: hifi_$BASENAME_h. ``` -#### 2.2.3. 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. -## 3. Statements +## [3] Statements -### 3.1. Types +### [3.1] Types -#### 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. +#### [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. -#### 3.1.2. Never rely on implicit type conversion. // NOT: floatValue = intValue; +#### [3.1.2] Never rely on implicit type conversion. // NOT: floatValue = intValue; -##### 3.1.2.1. Primitive types should use C style casting: +##### [3.1.2.1] Primitive types should use C style casting: ```cpp int foo = 1; @@ -384,7 +384,7 @@ uint8_t* barDataAt = (uint8_t*)&bar; // pointers to primitive types also use C s ``` -##### 3.1.2.2. Class pointers must use C++ style casting: +##### [3.1.2.2] Class pointers must use C++ style casting: ```cpp Player* player = getPlayer("forward"); @@ -394,9 +394,9 @@ 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) -#### 3.1.3. Use of *const* +#### [3.1.3] Use of *const* -##### 3.1.3.1. 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 @@ -404,7 +404,7 @@ void ClassBar::spam() const { } // doesn't modify instance of ClassBar, use cons ``` -##### 3.1.3.2. Place the const keyword before the type +##### [3.1.3.2] Place the const keyword before the type ```cpp void foo(const Bar& bar); @@ -414,7 +414,7 @@ void spam(const Foo* foo); ``` -##### 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. +##### [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; @@ -422,9 +422,9 @@ const glm::vec3& AABox::getCorner() const; ``` -#### 3.1.4. Type aliases +#### [3.1.4] Type aliases -##### 3.1.4.1. When creating a type alias, prefer the using keyword. +##### [3.1.4.1] When creating a type alias, prefer the using keyword. ```cpp template @@ -434,9 +434,9 @@ using Nodes = Vec ; ``` -### 3.2. Variables +### [3.2] Variables -#### 3.2.1. 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. @@ -450,7 +450,7 @@ getLineStats(&crosby, &dupuis, &kunitz); In these cases it should be left uninitialized rather than initialized to some phony value. -#### 3.2.2. 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). @@ -471,11 +471,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. -#### 3.2.3. 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) -#### 3.2.4. Class variables should never be declared public +#### [3.2.4] Class variables should never be declared public Use private variables and access functions instead. @@ -483,7 +483,7 @@ 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.* -#### 3.2.5. 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; @@ -496,7 +496,7 @@ 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. -#### 3.2.6. 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) @@ -513,15 +513,15 @@ if (!childNode) It is not necessarily defined by the C++ standard that ints and floats 0 are implemented as binary 0. -#### 3.2.7. 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. -### 3.3. Loops +### [3.3] Loops -#### 3.3.1. Loop variables should be initialized immediately before the loop. +#### [3.3.1] Loop variables should be initialized immediately before the loop. -#### 3.3.2. 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) { @@ -540,9 +540,9 @@ while (1) { ``` -### 3.4. Conditionals +### [3.4] Conditionals -#### 3.4.1. 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); @@ -557,7 +557,7 @@ if (isGoal) { Makes sure that the exceptions don't obscure the normal path of execution. This is important for both the readability and performance. -#### 3.4.2. 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) { @@ -568,7 +568,7 @@ if (isGoal) { ``` -#### 3.4.3. 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) { @@ -578,17 +578,17 @@ if (someVariable == 0) { ``` -### 3.5. Miscellaneous +### [3.5] Miscellaneous -#### 3.5.1. Constants and Magic Numbers +#### [3.5.1] Constants and Magic Numbers -##### 3.5.1.1. 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. -##### 3.5.1.2. 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) { @@ -598,7 +598,7 @@ bool checkValueLimit(int value) { ``` -##### 3.5.1.3. 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; @@ -606,7 +606,7 @@ const float LARGEST_VALUE = 10000.0f; ``` -#### 3.5.2. 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; @@ -617,25 +617,25 @@ penaltyMinutes = (minor + misconduct) * 2.0; ``` -#### 3.5.3. 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; ``` -#### 3.5.4. 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; ``` -## 4. Layout and Comments +## [4] Layout and Comments -### 4.1. Layout +### [4.1] Layout -#### 4.1.1. Basic indentation should be 4. +#### [4.1.1] Basic indentation should be 4. ```cpp if (player.isCaptain) { @@ -644,7 +644,7 @@ if (player.isCaptain) { ``` -#### 4.1.2. Use inline braces for block layout +#### [4.1.2] Use inline braces for block layout ```cpp while (!puckHeld) { @@ -659,7 +659,7 @@ while (!puckHeld) { ``` -#### 4.1.3. The class declarations should have the following form: +#### [4.1.3] The class declarations should have the following form: ```cpp class GoalieStick : public HockeyStick { @@ -673,7 +673,7 @@ private: ``` -#### 4.1.4. Method definitions should have the following form: +#### [4.1.4] Method definitions should have the following form: ```cpp void goalCelebration() { @@ -682,7 +682,7 @@ void goalCelebration() { ``` -#### 4.1.5. 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) { @@ -705,7 +705,7 @@ if (isScorer) { ``` -#### 4.1.6. 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++) { @@ -714,7 +714,7 @@ for (int i = 0; i < GRETZKY_NUMBER; i++) { ``` -#### 4.1.7. A while statement should have the following form: +#### [4.1.7] A while statement should have the following form: ```cpp while (!whistle) { @@ -723,7 +723,7 @@ while (!whistle) { ``` -#### 4.1.8. A do-while statement should have the following form: +#### [4.1.8] A do-while statement should have the following form: ```cpp do { @@ -732,7 +732,7 @@ do { ``` -#### 4.1.9. Switch/Case Statements: +#### [4.1.9] Switch/Case Statements: A switch statements should follow the following basic formatting rules: @@ -782,7 +782,7 @@ switch (jerseyNumber) { ``` -#### 4.1.10. A try-catch statement should have the following form: +#### [4.1.10] A try-catch statement should have the following form: ```cpp try { @@ -793,7 +793,7 @@ try { ``` -#### 4.1.11. Single statement if-else, for or while statements must be written with braces. +#### [4.1.11] Single statement if-else, for or while statements must be written with braces. ```cpp // GOOD: @@ -806,9 +806,9 @@ for (int i = 0; i < numItems; i++) item[i].manipulate(); ``` -### 4.2 White space +### [4.2] White space -#### 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. +#### [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; @@ -826,7 +826,7 @@ v = w * (x + z); ``` -#### 4.2.2. 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); @@ -834,7 +834,7 @@ setLine(leftWing, center, rightWing, leftDefense, rightDefense); ``` -#### 4.2.3. Commas should be followed by a white space. +#### [4.2.3] Commas should be followed by a white space. ```cpp setLine(leftWing, center, rightWing, leftDefense, rightDefense); @@ -842,14 +842,14 @@ setLine(leftWing, center, rightWing, leftDefense, rightDefense); ``` -#### 4.2.4. Semicolons in for statments should be followed by a space character. +#### [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++){ ``` -#### 4.2.5. 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. @@ -863,7 +863,7 @@ setCaptain(ovechkin); ``` -#### 4.2.6. 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(); @@ -878,7 +878,7 @@ penguins.hireCoach(); ``` -#### 4.2.7. 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: @@ -894,7 +894,7 @@ charaSlapShotSpeed = computeShot(stickFlex, weber); A change to the length of a variable in these sections causes unnecessary changes to the other lines. -#### 4.2.8. 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. @@ -906,7 +906,7 @@ Expressions, including C++ initializers and JavaScript object notation literals, The following are all acceptable: -``` +```cpp shootOnNet(puckVelocity, playerStrength, randomChance); @@ -948,13 +948,13 @@ aCPlusPlusFunctionOfTwoLambdas([](gpu::Batch& batch) { ``` -### 4.3 Comments +### [4.3] Comments -#### 4.3.1. 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. -#### 4.3.2. 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 jsdoc or Doxygen comments. @@ -966,7 +966,7 @@ An exception to this rule applies for jsdoc or Doxygen comments. There should be a space between the "//" and the actual comment -#### 4.3.3. 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) { @@ -982,7 +982,7 @@ while (true) { ``` -#### 4.3.4. 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. @@ -1002,7 +1002,7 @@ Boilerplates should include the filename, location, creator, copyright, and Apac ``` -#### 4.3.5. 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. From 7e28b225df35b474d4f7805a18e77c6313967161 Mon Sep 17 00:00:00 2001 From: Anthony Thibault Date: Fri, 29 Mar 2019 15:55:09 -0700 Subject: [PATCH 7/7] minor edits --- CODING_STANDARD.md | 20 ++++++-------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/CODING_STANDARD.md b/CODING_STANDARD.md index 9f58105914..17f7ecb2f2 100644 --- a/CODING_STANDARD.md +++ b/CODING_STANDARD.md @@ -287,7 +287,7 @@ public: void addBlaToList(Blah* bla) { _blas.append(bla); } // Allowed, because this is a simple method - int calculateCircumference () { return PI * pow(_radius, 2.0); } + int calculateCircumference() { return PI * pow(_radius, 2.0); } // this routine needs to be fast, we'll inline it below void doSomethingHighPerformance() const; @@ -826,7 +826,7 @@ v = w * (x + z); ``` -#### [4.2.2] 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. ```cpp setLine(leftWing, center, rightWing, leftDefense, rightDefense); @@ -834,22 +834,14 @@ setLine(leftWing, center, rightWing, leftDefense, rightDefense); ``` -#### [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. +#### [4.2.3] 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++){ ``` -#### [4.2.5] Declaring and Calling Functions +#### [4.2.4] 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. @@ -878,7 +870,7 @@ penguins.hireCoach(); ``` -#### [4.2.7] Avoid adding optional spaces across multi-line statements and adjacent statements. +#### [4.2.6] Avoid adding optional spaces across multi-line statements and adjacent statements. Avoid the following: @@ -894,7 +886,7 @@ charaSlapShotSpeed = computeShot(stickFlex, weber); A change to the length of a variable in these sections causes unnecessary changes to the other lines. -#### [4.2.8] Multi-line statements must have all n+1 lines indented at least one level (four spaces). +#### [4.2.7] 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.