CODESTYLE.md

   1 ## Legacy code
   2 In case you're doing minor changes in existing legacy code - use existing code style as you see in that code.
   3 Otherwise follow guidelines below.
   4
   5 ## Indentation and alignment:
   6 Code block indentation and alignment of hyphenated continuations - tabs.
   7 Alignment of trailing comments - also tabs.
   8 All other alignment in the middle of text line (if need) - spaces.
   9
  10 ## Spaces and parenthesis:
  11 ``` Examples:
  12 // No space between parenthesis and function name, no space in empty arguments list:
  13 void FunctionWithoutArgs();
  14
  15 // Spaces between arguments, but no spaces between parenthesis and contained argument:
  16 void ConstFunctionWithArgs(int i, std::string s) const;
  17
  18 // Spaces between expression elements and after if, no spaces between parenthesis and contained stuff:
  19 if (condition1 && (condition2 || condition3)) {
  20 }
  21
  22 // Space between try and opening brace, spaces around catch:
  23 try {
  24 } catch (std::exception &) {
  25 }
  26 int arr[] = {1, 2, 3};      // - space both sides of equal sign here
  27 int i{};                    // - no space between variable and list initializer's brace
  28 i = arr[1];                 // - simple assignment - space surrounds both sides of equal sign
  29 i+= arr[2];                 // - incremental assignment - space only on the right
  30 void *ptr_i = (void *)&i;   // - pointer: space between target type and asterisk
  31 int &ref_i = i;             // - reference: space between target type and amperans
  32
  33 // Complex ternary expressions should have parenthesis to segregate things:
  34 int ternary_result1 = simple_condition ? 1 : 2;
  35 int ternary_result2 = (complex && condition) ? 1 : 2;
  36 int ternary_result3 = simple_condition ? ((complex && condition) ? 1 : 2) : ((complex && condition) ? 3 : 4);
  37 ```
  38
  39 ## Line length limit:
  40 110 characters, buts its a soft limit, i.e. prefer better readability more than fiting limit.
  41 Trailing comments are not affected by this limit at all.
  42
  43 ## Code braces:
  44 Use direct (same line) braces for class-es/struct-s/union-s, functions, namespaces
  45 Use egyptian braces for if-s, loop-s, try..catch-es, lambda-s
  46 In case of if..elseif.. with long complex code within block - use empty line to accent end of code block.
  47 In case code-block-start operator has short own condition and has as child single another code-block-starter, you may put that secondary operator at same line as first one and use single indentation for its code block.
  48 In case of very short inlined class methods - you may write method definition's code block as single line.
  49 In all other cases put any nested operator and its code block starting from separate line and with its own indentation level.
  50 ``` Examples:
  51 namespace Foo
  52 {
  53         struct Bar
  54         {
  55                 int Short() const { return _result; }
  56
  57                 void Baz() const
  58                 {
  59                         if (short_cond) try {
  60                                 SomeCode();
  61                         } catch (...) {
  62                         }
  63
  64                         if (long && complicated && condition) {
  65                                 try {
  66                                         SomeCode();
  67                                 } catch (...) {
  68                                 }
  69                         }
  70                 }
  71
  72                 void Qux()
  73                 {
  74                         if (cond1) {
  75                                 SomeShortCode();
  76                         } else if (cond2) {
  77                                 SomeShortCode();
  78                         } else {
  79                                 SomeShortCode();
  80                         }
  81
  82                         if (cond1) {
  83                                 Some();
  84                                 Long();
  85                                 Code();
  86
  87                         } else if (cond2) {
  88                                 Some();
  89                                 Long();
  90                                 Code();
  91
  92                         } else {
  93                                 Some();
  94                                 Long();
  95                                 Code();
  96                         }
  97                 }
  98         };
  99 };
 100 ```
 101
 102 ## Hyphenated continuations:
 103 Indent second line of condition using two tabs to separate it from code block.
 104 Put hyphenated operators on new line's beginning.
 105 ``` Example:
 106 if (i == 10
 107                 || i == 20
 108                 || i == 30) {
 109         SomeCode();
 110 }
 111 ```
 112
 113 ## Naming:
 114 Use CamelCase for name of enums, namespaces, classes, structures, functions and methods
 115 Use snake_case for all variables, however:
 116 &nbsp;&nbsp; Private and protected class's fields - prefix by '\_'
 117 &nbsp;&nbsp; Static variables - prefix by 's\_'
 118 &nbsp;&nbsp; Global nonstatic variables - prefix by 'g\_'
 119 Use UPPER_CASE_WITH_UNDERSCORES for macroses, values of enum-s.
 120 Additionally values of enums must be prefixes with a abbreviation of corresponding enum's name.
 121 Templates:
 122 &nbsp;&nbsp; For template arguments that represent type name - use CamelCaseT (camel case with T suffix).
 123 &nbsp;&nbsp; For template arguments that typed constant value - use UPPER_CASE_WITH_UNDERSCORES_T.
 124 &nbsp;&nbsp; If template function represents 'internal' implementation for some nearby non-templated functions - you may add T suffix for its name to clearly denote this.
 125 ``` Examples:
 126 enum SomeEnum
 127 {
 128         SE_ZERO = 0,
 129         SE_ONE  = 1,
 130         SE_TWO  = 2
 131 };
 132
 133 int g_counter = 0;
 134
 135 class FooBar
 136 {
 137         int _private_field;
 138
 139 public:
 140         void CallMe(SomeEnum argument)
 141         {
 142                 static int s_static_var;
 143                 int local_var = argument + _private_field;
 144                 s_static_var = std::max(local_var, s_static_var);
 145                 ++g_counter;
 146         }
 147 };
 148
 149 template < class ClassT, int VALUE_T >
 150         ClassT TemplateFunction(int arg)
 151 {
 152         return ClassT(arg + VALUE_T);
 153 }
 154
 155 ```
 156
 157 ## class/struct:
 158 Use struct if your class exposes some public data fields or/and only public methods otherwise prefer using class.
 159
 160 ## class/struct layouts:
 161 ```
 162 class FooBar
 163 {
 164         int _private_field;
 165         void PrivateMethod();
 166
 167 protected:
 168         int _protected_field;
 169         void ProtectedMethod();
 170
 171 public:
 172         void PublicMethod();
 173 };
 174
 175 struct FooBar
 176 {
 177         int public_field;
 178         void PublicMethod();
 179 };
 180 ```
 181
 182
 183 ## File naming:
 184 Use CamelCase.cpp unless you're adding file into a directory that already have lots of files with different naming convention. In such case follow existing conventions.