From b290782d31bfc1ea27f01b6a35127b0abddb669a Mon Sep 17 00:00:00 2001 From: "Efimov Alexander/AI Tools Lab/./Samsung Electronics" Date: Tue, 9 Oct 2018 18:06:18 +0300 Subject: [PATCH] Add low level code style description (#1736) Add code_style.rst document that describes C++ formatting and naming conventions Signed-off-by: Efimov Alexander --- contrib/nnc/doc/codestyle.rst | 182 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 contrib/nnc/doc/codestyle.rst diff --git a/contrib/nnc/doc/codestyle.rst b/contrib/nnc/doc/codestyle.rst new file mode 100644 index 0000000..5624893 --- /dev/null +++ b/contrib/nnc/doc/codestyle.rst @@ -0,0 +1,182 @@ +Low-level issues +================ + +Naming styles: +-------------- + +- `snake_case` - name starts with lower case, words divided by underscore +- `CamelCase` - name starts with Upper case, words starts with Upper case, no divider +- `camelCase` - name starts with lower case, words(except first) starts with Upper case, no divider +- `_camelCase` - name starts with underscore, first word starts with lower case, other with Upper case, no divider +- `ALL_UPPER` - all characters in Upper case, words divided by underscore + +General indentations and limits: +-------------------------------- + +- Line of code should be no longer than 100 characters(including comments) +- Opening brace should stay on the same line with corresponding statement +- Stick **\*** and **&** in variable declaration to type name: **Shape* s;** +- Do not declare multiple pointer or reference variables separated by commas +- Block contents of **{}** should be indented with 2 spaces, excluding: + + + access modifiers in classes + + namespaces + + initializer lists + + **case** contents + +- No tabs allowed, only spaces + +Directories and file names: +--------------------------- + +- Directory names should be in snake_case +- File names should be in CamelCase(SomeFile.cpp, SomeFile.h) + +Namespaces: +----------- + +- Namespaces names should be in came_case, one word names are prefered: **cli**, **mir**, **some_long_namespace** +- Use unnamed namespaces to hide all non-interface functions and classes of translation unit +- No **using namespace** or **using namespace::classname** in headers +- Namespace contents are not indented + +Enum & Macros: +-------------- + +- Enum(class and non-class) names should be in `CamelCase` +- Elements of class enum should be in `camelCase` +- Non-class enum elements should be in `ALL_UPPER` case +- Macro names should be in `ALL_UPPER` case + +Functions & Methods: +-------------------- + +- Global functions and method names should be in `camelCase` +- Virtual methods should be marked with **override** in derived class + +Global variables: +----------------- + +- Global variables(static && non static) should be in `camelCase` (including constant data) + +Local variables: +---------------- + +- Names should be in snake_case + +Classes & Structures & Unions: +------------------------------ + +- Names of classes, structures and unions should be in `CamelCase` +- Private(and protected) data should be in `_camelCase` +- Public data should be in `camelCase` +- Classes should have only one section of each type(public, private) +- Access modifiers(public, private, protected) should not be indented relative to class declaration +- Sections should go in order: public, protected, private +- Methods go first, then data +- If class has constructors they should be first defined methods +- If class has destructor it should go after constructors + +.. code-block:: c++ + + class AnotherFoo : public Foo { + public: + explicit AnotherFoo() = default; + ~AnotherFoo() = default; + + /** + * @brief Definitely does something + */ + void doSomething() noexcept { + //...// + } + protected: + private: + int _foosInt; + } + +Templates: +---------- + +- Add space before angle brackets in template declaration and no spaces inside: **template ** +- Do not add space before angle brackets in template instantiation and no spaces inside: **foo<12321>()** +- Use **typename** instead of **class** in template parameters + +Control flow contructions: +-------------------------- + +- Function call should have no spaces around parentheses and have spaces after commas: **someFunc(arg1, arg2);** +- **if**, **while**, **for** should have space after reserved word: **if (cond)** **while (cond)** **for (cond)** +- **switch** should always have **default** case, if all cases are checked and **default** is redundant, place **assert(false)** in it +- Avoid redundant braces inside switch **case** +- **case** labels should be indented by 2 spaces relative to **switch** +- Code in **code** section sould be indented by 2 spaces relative to corresponding **case** +- Do not use non-empty cases with fallthrough( i.e. always add **break** ) +- Braces after **if**, **for**, **while** are optional if condition and predicate code are one lined +- If **if** operator has else branch it's content should be one lined too to apply "no braces" rule: + +.. code-block:: c++ + + if (cond) + a = this; + else + b = that; + + +.. code-block:: c++ + + switch(cond) { + case 0: + case 1: + doThis(); + break; + case 2: + doThat(); + break; + case 3: { + int x = 42; + useX(x); + } + default: + assert(false); + } + + +Comments: +--------- + +- Function, methods(except trivial getters and setters), classes, structures, enums, should be commented in described doxygen format. +- All mentioned entities should have **@brief** field, exception is getters, they could define **@return** instead +- Functions have to describe their arguments(**@param**), template arguments(**@tparam**), return value if non-void(**@return**), what kinds of exceptions could be thrown(**@throws**) +- One line comments starts with /// +- Multiline comments should start on a second line, all lines start from *****, text separated from ***** with whitespace and goes like this: + +.. code-block:: c++ + + /** + * @brief some method that does something + * @param arg some input data + * continue arg explanation on second line + * @throws some exceptions + * continue explanation of throws + * + * Detailed description + */ + +Type aliases: +------------- + +- Use **using** instead of **typedef** +- Aliases for basic types should have names in `snake_case`: **using axis_t = int32_t;** +- Aliases for user-defined types should have names in `CamelCase`: **using Shape = nnc::mir::Shape;** + +Misc: +----- + +- No spaces around braces in initializer lists, spaces after commas: **{1, 2, 3}** +- No spaces around square brackets in arrays: **int a[5];** **arr[53] = 1;** +- Declare methods as const if they do not change the object +- Declare objects and pointers with const modifier if possible +- Always add spaces around assignment operators(**=**, **+=**, etc): **a = 32;** +- Add spaces around operators reasonably, do not add spaces around operators if you want to group operations without parentheses: **res = a*b + c*d;** +- Add **noexcept** specifier if function does not throw -- 2.7.4