docs/CODE_GUIDELINES.md

   1 # Code Guidelines
   2
   3 ![Kodi Logo](https://github.com/xbmc/xbmc/raw/master/docs/resources/banner_slim.png)
   4
   5 ## Table of Contents
   6 * [1. Motivation](#1-motivation)
   7 * [2. Language standard](#2-language-standard)
   8 * [3. Formatting](#3-formatting)
   9   * [3.1. Braces](#31-braces)
  10   * [3.2. Indentation](#32-indentation)
  11   * [3.3. Control statements](#33-control-statements)
  12     * [3.3.1. if else](#331-if-else)
  13     * [3.3.2. switch case](#332-switch-case)
  14     * [3.3.3. try catch](#333-try-catch)
  15   * [3.4. Whitespace](#34-whitespace)
  16   * [3.5. Vertical alignment](#35-vertical-alignment)
  17 * [4. Statements](#4-statements)
  18 * [5. Declarations](#5-declarations)
  19   * [5.1. Declarations](#51-declarations)
  20   * [5.2. Multiple declarations](#52-multiple-declarations)
  21   * [5.3. Pointer and reference types](#53-pointer-and-reference-types)
  22   * [5.4. const and other modifiers](#54-const-and-other-modifiers)
  23   * [5.5. Initialization](#55-initialization)
  24 * [6. Scoping](#6-scoping)
  25   * [6.1. Namespaces](#61-namespaces)
  26   * [6.2. Local functions](#62-local-functions)
  27 * [7. Headers](#7-headers)
  28   * [7.1. Header order](#71-header-order)
  29   * [7.2. Use C++ wrappers for C headers](#72-use-c-wrappers-for-c-headers)
  30 * [8. Naming](#8-naming)
  31   * [8.1. Namespaces](#81-namespaces)
  32   * [8.2. Constants](#82-constants)
  33   * [8.3. Enums](#83-enums)
  34   * [8.4. Interfaces](#84-interfaces)
  35   * [8.5. Classes](#85-classes)
  36   * [8.6. Structs](#86-structs)
  37   * [8.7. Methods](#87-methods)
  38   * [8.8. Variables](#88-variables)
  39     * [Member variables](#member-variables)
  40     * [Global variables](#global-variables)
  41 * [9. Comments](#9-comments)
  42   * [9.1. General](#91-general)
  43   * [9.2. Doxygen](#92-doxygen)
  44 * [10. Logging](#10-logging)
  45 * [11. Classes](#11-classes)
  46   * [11.1. Member visibility](#111-member-visibility)
  47   * [11.2. Const correctness](#112-const-correctness)
  48   * [11.3. Overriding virtual functions](#113-overriding-virtual-functions)
  49   * [11.4. Default member initialization](#114-default-member-initialization)
  50   * [11.5. Destructors in interfaces](#115-destructors-in-interfaces)
  51   * [11.6. Constructor Initialization Lists](#116-constructor-initialization-lists)
  52 * [12. Other conventions](#12-other-conventions)
  53   * [12.1. Output parameters](#121-output-parameters)
  54   * [12.2. Casts](#122-casts)
  55   * [12.3. `NULL` vs `nullptr`](#123-null-vs-nullptr)
  56   * [12.4. auto](#124-auto)
  57   * [12.5. `for` loops](#125-for-loops)
  58   * [12.6. Include guards](#126-include-guards)
  59   * [12.7. Type aliases](#127-type-aliases)
  60   * [12.8. `goto`](#128-goto)
  61   * [12.9. Macros](#129-macros)
  62   * [12.10. constexpr](#1210-constexpr)
  63   * [12.11. `std::string` vs `std::string_view`](#1211-stdstring-vs-stdstring_view)
  64
  65 ## 1. Motivation
  66 When working in a large group, the two most important values are readability and maintainability. We code for other people, not computers. To accomplish these goals, we have created a unified set of code conventions.
  67
  68 In the repository root directory, there is a [`.clang-format`](https://github.com/xbmc/xbmc/blob/master/.clang-format) file that implements the rules as specified here. You are encouraged to run [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html) on any newly created files. It is currently not recommended to do so on preexisting files because all the formatting changes will clutter your commits and pull request.
  69
  70 When you create a pull request, the PR build job will run `clang-format` on your commits and provide patches for any parts that don't satisfy the current `.clang-format` rules. You should apply these patches and amend your pull request accordingly.
  71
  72 Conventions can be bent or broken in the interest of making code more readable and maintainable. However, if you submit a patch that contains excessive style conflicts, you may be asked to improve your code before your pull request is reviewed.
  73
  74 **[back to top](#table-of-contents)**
  75
  76 ## 2. Language standard
  77
  78 We currently target the C++17 language standard. Do use C++17 features when possible (and supported by all target platforms). Do not use C++20 features.
  79
  80 **[back to top](#table-of-contents)**
  81
  82 ## 3. Formatting
  83
  84 ### Line length
  85 The `ColumnLimit` in `.clang-format` is set to `100` which defines line length (in general where lines should be broken) that allows two editors side by side on a 1080p screen for diffs.
  86
  87 ### 3.1. Braces
  88 Curly braces always go on a new line.
  89
  90 ```cpp
  91 for (int i = 0; i < t; i++)
  92 {
  93   [...]
  94 }
  95
  96 if (true)
  97 {
  98   [...]
  99 }
 100
 101 class Dummy
 102 {
 103   [...]
 104 };
 105 ```
 106
 107 ### 3.2. Indentation
 108 Use spaces as tab policy with an indentation size of 2.
 109 Opening curly braces increase the level of indentation. Closing curly braces decrease the level of indentation.
 110
 111 **Exception:** Do not indent namespaces to simplify nesting them and wrapping *.cpp* files in a namespace.
 112
 113 ```cpp
 114 namespace KODI
 115 {
 116 namespace UTILS
 117 {
 118
 119 class ILogger
 120 {
 121 public:
 122   virtual void Log(...) = 0;
 123   virtual ~ILogger() {}
 124 }
 125
 126 }
 127 }
 128 ```
 129
 130 ### 3.3. Control statements
 131 Insert a new line before every:
 132 * else in an if statement
 133 * catch in a try statement
 134
 135 #### 3.3.1. if else
 136 Put the consequent on a new line if not in curly braces anyway. Keep `else if` statements on one line. Do not put a condition and a following statement on a single line.
 137
 138 ✅ Good:
 139 ```cpp
 140 if (true)
 141   return;
 142
 143 if (true)
 144 {
 145   [...]
 146 }
 147 else if (false)
 148 {
 149   return;
 150 }
 151 else
 152   return;
 153 ```
 154
 155 ❌ Bad:
 156 ```cpp
 157 if (true) return;
 158 ```
 159
 160 #### 3.3.2. switch case
 161
 162 ```cpp
 163 switch (cmd)
 164 {
 165   case x:
 166   {
 167     doSomething();
 168     break;
 169   }
 170   case x:
 171   case z:
 172     return true;
 173   default:
 174     doSomething();
 175 }
 176 ```
 177
 178 #### 3.3.3. try catch
 179
 180 ```cpp
 181 try
 182 {
 183   [...]
 184 }
 185 catch (std::exception& e)
 186 {
 187   [...]
 188   throw;
 189 }
 190 catch (...)
 191 {
 192   [...]
 193 }
 194 ```
 195
 196 ### 3.4. Whitespace
 197 Conventional operators have to be surrounded by one space on each side.
 198 ```cpp
 199 a = (b + c) * d;
 200 ```
 201 Control statement keywords have to be separated from opening parentheses by one space.
 202 ```cpp
 203 while (true);
 204 for (int i = 0; i < x; i++);
 205 ```
 206 When conditions are used without parentheses, it is preferable to add a new line, to make the next block of code more readable.
 207 ```cpp
 208 if (true)
 209   return;
 210
 211 if (true)
 212 ```
 213 Commas have to be followed by one space.
 214 ```cpp
 215 void Dummy::Method(int a, int b, int c);
 216 ```
 217 Initializer lists have one space after each element (including comma), but no surrounding spaces.
 218 ```cpp
 219 constexpr int aNiceArray[] = {1, 2, 3};
 220 ```
 221
 222 ### 3.5. Vertical alignment
 223 Do not use whitespace to vertically align around operators or values. This causes problems on code review if one needs to realign all values to their new position, producing unnecessarily large diffs.
 224
 225 ✅ Good:
 226 ```cpp
 227 int value1{1};
 228 int value2{2};
 229 CExampleClass* exampleClass{};
 230 CBiggerExampleClass* biggerExampleClass{};
 231 exampleClass = new CExampleClass(value1, value2);
 232 biggerExampleClass = new CBiggerExampleClass(value1, value2);
 233 exampleClass->InitExample();
 234 biggerExampleClass->InitExample();
 235 ```
 236
 237 ❌ Bad:
 238 ```cpp
 239 int                  value1             {1};
 240 int                  value2             {2};
 241 [...]
 242 CExampleClass       *exampleClass       {};
 243 CBiggerExampleClass *biggerExampleClass {};
 244 [...]
 245 exampleClass       = new CExampleClass      (value1, value2);
 246 biggerExampleClass = new CBiggerExampleClass(value1, value2);
 247 [...]
 248 exampleClass      ->InitExample();
 249 biggerExampleClass->InitExample();
 250 ```
 251
 252 ### 3.6. Superfluous `void`
 253
 254 Do not write `void` in empty function parameter declarations.
 255
 256 ✅ Good:
 257 ```cpp
 258 void Test();
 259 ```
 260
 261 ❌ Bad:
 262 ```cpp
 263 void Test(void);
 264 ```
 265
 266 ### 3.7. Exceptions to the Formatting Rules For Better Readability
 267 There are some special situations where vertical alignment and longer lines does greatly aid readability, for example the initialization of some table-like multiple row structures. In these **rare** cases exceptions can be made to the formatting rules on vertical alignment, and the defined line length can be exceeded.
 268
 269 To prevent the layout from being reformatted, tell `clang-format` to [disable formatting](https://clang.llvm.org/docs/ClangFormatStyleOptions.html#disabling-formatting-on-a-piece-of-code) on that section of code by surrounding it with the special comments `// clang-format off` and `// clang-format on`.
 270 For example:
 271 ```
 272 // clang-format off
 273 static const CGUIDialogMediaFilter::Filter filterList[] = {
 274   { "movies",       FieldTitle,         556,    SettingType::String,  "edit",   "string",   CDatabaseQueryRule::OPERATOR_CONTAINS },
 275   { "movies",       FieldRating,        563,    SettingType::Number,  "range",  "number",   CDatabaseQueryRule::OPERATOR_BETWEEN },
 276   { "movies",       FieldUserRating,    38018,  SettingType::Integer, "range",  "integer",  CDatabaseQueryRule::OPERATOR_BETWEEN },
 277   ...
 278   { "songs",        FieldSource,        39030,  SettingType::List,    "list",   "string",   CDatabaseQueryRule::OPERATOR_EQUALS },
 279 };
 280 // clang-format on
 281  ```
 282 The other code guidelines will still need to be applied within the delimited lines of code, but with `clang-format` off care will be needed to check these manually. Using vertical alignment means that sometimes the entire block of code may need to be realigned, good judgement should be used in each case with the objective of preserving readability yet minimising impact.
 283
 284 This is to be used with discretion, marking large amounts of code to be left unformatted by `clang-format` without reasonable justification will be rejected.
 285
 286 **[back to top](#table-of-contents)**
 287
 288 ## 4. Statements
 289
 290 ### 4.1. Multiple statements
 291 Do not put multiple statements on a single line. Always use a new line for a new statement. It is much easier to debug if one can pinpoint a precise line number.
 292
 293 ✅ Good:
 294 ```cpp
 295 std::vector<std::string> test;
 296 test.push_back("foobar");
 297 ```
 298
 299 ❌ Bad:
 300 ```cpp
 301 std::vector<std::string> test; test.push_back("foobar");
 302 ```
 303
 304 ### 4.2. `switch` default case
 305
 306 In every `switch` structure, always include a `default` case, unless switching on an enum and all enum values are explicitly handled.
 307
 308 **[back to top](#table-of-contents)**
 309
 310 ## 5. Declarations
 311
 312 ### 5.1. Declarations
 313
 314 Always declare a variable close to its use and not before a block of code that does not use it.
 315
 316 ✅ Good:
 317 ```cpp
 318 int x{3};
 319 CLog::Log("test: {}", x); // variable used just after its declaration
 320 ```
 321
 322 ❌ Bad:
 323 ```cpp
 324 int x{3}; // variable not immediately used by the next block of code
 325 [...many lines of code that do not use variable x...]
 326 CLog::Log("test: {}", x);
 327 ```
 328
 329 ### 5.2. Multiple declarations
 330 Do not put multiple declarations on a single line. This avoids confusion with differing pointers, references, and initialization values on the same line (cf. [ISO C++ guidelines](http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es10-declare-one-name-only-per-declaration)).
 331
 332 ✅ Good:
 333 ```cpp
 334 char* a;
 335 char b;
 336 ```
 337
 338 ❌ Bad:
 339 ```cpp
 340 char* a, b;
 341 ```
 342
 343 ### 5.3. Pointer and reference types
 344 Left-align `*` and `&` to the base type they modify.
 345
 346 ✅ Good:
 347 ```cpp
 348 char* a;
 349 void test(const std::string& b);
 350 ```
 351
 352 ❌ Bad:
 353 ```cpp
 354 char *a;
 355 char * b;
 356 void test(const std::string &b);
 357 ```
 358
 359 (This is adopted from the HP C++ Coding Guidelines: "The characters * and & are to be written with the type of variables instead of with the name of variables in order to emphasize that they are part of the type definition.")
 360
 361 ### 5.4. `const` and other modifiers
 362 Place `const` and similar modifiers in front of the type they modify.
 363
 364 ✅ Good:
 365 ```cpp
 366 void Test(const std::string& a);
 367 const int* const someIntPointer;
 368 ```
 369
 370 ❌ Bad:
 371 ```cpp
 372 void Test(std::string const& a);
 373 int const * const someIntPointer;
 374 ```
 375
 376 ### 5.5. Initialization
 377
 378 Make sure that variables are initialized appropriately at declaration or soon afterwards. This is especially important for fundamental type variables that do not have any constructor. Zero-initialize with `{}`.
 379
 380 ✅ Good:
 381 ```cpp
 382 int x{3};
 383 int* y{nullptr};
 384 bool z = false;
 385 std::string text; // not primitive
 386 KindOfStruct theStruct{}; // POD structures or structures with uninitalised members must be initialised with empty brackets
 387 Log::Log("test: {}, {}, {}", x, y, z);
 388 ```
 389
 390 ❌ Bad:
 391 ```cpp
 392 int x; // used uninitialized
 393 int* y = nullptr; // default-initialization not using {}
 394 bool z{}; // no value explicitly declared for fundamental type, preferable for better reading
 395 std::string text{}; // has its default constructor
 396 Log::Log("test: {}, {}, {}", x, y, z);
 397 ```
 398
 399 We allow variable initialization using any of the C++ forms `{}`, `=` or `()`.
 400
 401 However, we would like to point out some optional suggestions to follow:
 402 - Prefer the `{}` form to others, because this permits explicit type checking to avoid unwanted narrowing conversions.
 403 - Prefer the `{}` form when initializing a class/struct variable.
 404 - Specify an explicit initialization value, at least for fundamental types.
 405
 406 **[back to top](#table-of-contents)**
 407
 408 ## 6. Scoping
 409
 410 ### 6.1. Namespaces
 411
 412 Try to put all code into appropriate namespaces (e.g. following directory structure) and avoid polluting the global namespace.
 413
 414 ### 6.2. Local functions
 415
 416 Put functions local to a compilation unit into an anonymous namespace.
 417
 418 ✅ Good:
 419 ```cpp
 420 namespace
 421 {
 422
 423 void test();
 424
 425 } // unnamed namespace
 426 ```
 427
 428 ❌ Bad:
 429 ```cpp
 430 static void test();
 431 ```
 432
 433 **[back to top](#table-of-contents)**
 434
 435 ## 7. Headers
 436 ### 7.1. Header order
 437 Included header files have to be sorted (case sensitive) alphabetically to prevent duplicates and allow better overview, with an empty line clearly separating sections.
 438
 439 Header order has to be:
 440 * Own header file
 441 * Other Kodi includes (platform independent)
 442 * Other Kodi includes (platform specific)
 443 * C and C++ system files
 444 * Other libraries' header files
 445 * special Kodi headers (PlatformDefs.h, system.h and system_gl.h)
 446
 447 ```cpp
 448 #include "PVRManager.h"
 449
 450 #include "Application.h"
 451 #include "ServiceBroker.h"
 452 #include "addons/AddonInstaller.h"
 453 #include "dialogs/GUIDialogExtendedProgressBar.h"
 454 #include "messaging/ApplicationMessenger.h"
 455 #include "messaging/ThreadMessage.h"
 456 #include "messaging/helpers/DialogHelper.h"
 457 #include "music/MusicDatabase.h"
 458 #include "music/tags/MusicInfoTag.h"
 459 #include "network/Network.h"
 460 #include "pvr/addons/PVRClients.h"
 461 #include "pvr/channels/PVRChannel.h"
 462 #include "settings/Settings.h"
 463 #include "threads/SingleLock.h"
 464 #include "utils/JobManager.h"
 465 #include "utils/Variant.h"
 466 #include "utils/log.h"
 467 #include "video/VideoDatabase.h"
 468
 469 #include <cassert>
 470 #include <utility>
 471
 472 #include <libavutil/pixfmt.h>
 473 ```
 474
 475 If the headers aren't sorted, either do your best to match the existing order, or precede your commit with an alphabetization commit.
 476
 477 If possible, avoid including headers in another header. Instead, you can forward-declare the class and use a `std::unique_ptr` (or similar):
 478
 479 ```cpp
 480 class CFileItem;
 481
 482 class Example
 483 {
 484   ...
 485   std::unique_ptr<CFileItem> m_fileItem;
 486 }
 487 ```
 488
 489 ### 7.2. Use C++ wrappers for C headers
 490 To use C symbols use C++ wrappers headers, by using the `std` namespace prefix.
 491
 492 ✅ Good:
 493 ```cpp
 494 #include <cstring>
 495 [...]
 496 size_t n = std::strlen(str);
 497 ```
 498
 499 ❌ Bad:
 500 ```cpp
 501 #include <string.h> // C header
 502 [...]
 503 size_t n = strlen(str); // missing std namespace
 504 ```
 505
 506 **[back to top](#table-of-contents)**
 507
 508 ## 8. Naming
 509 ### 8.1. Namespaces
 510 Use upper case with underscores.
 511 ```cpp
 512 namespace KODI
 513 {
 514 [...]
 515 } // namespace KODI
 516 ```
 517
 518 ### 8.2. Constants
 519 Use upper case with underscores.
 520 ```cpp
 521 constexpr int MY_CONSTANT = 1;
 522 ```
 523
 524 ### 8.3. Enums
 525 Use PascalCase for the enum name and upper case with underscores for the values.
 526 ```cpp
 527 enum class Dummy
 528 {
 529   VALUE_X,
 530   VALUE_Y
 531 };
 532 ```
 533
 534 ### 8.4. Interfaces
 535 Use PascalCase and prefix with an uppercase I. Filename has to match the interface name without the prefixed I, e.g. Logger.h
 536 ```cpp
 537 class ILogger
 538 {
 539 public:
 540   virtual void Log(...) = 0;
 541   virtual ~ILogger() {}
 542 }
 543 ```
 544
 545 ### 8.5. Classes
 546 Use PascalCase and prefix with an uppercase C. Filename has to match the class name without the prefixed C, e.g. Logger.cpp
 547 ```cpp
 548 class CLogger : public ILogger
 549 {
 550 public:
 551   void Log(...) override;
 552 }
 553 ```
 554
 555 ### 8.6. Structs
 556 Use PascalCase.
 557 ```cpp
 558 struct InfoChar
 559 {
 560   bool m_isBold{false};
 561 }
 562 ```
 563
 564 ### 8.7. Methods
 565 Use PascalCase always, uppercasing the first letter even if the methods are private or protected.
 566 Method parameters start with lower case and follow CamelCase style, without type prefixing (Systems Hungarian notation).
 567 ```cpp
 568 void MyDummyClass::DoSomething(int limitBound);
 569 ```
 570
 571 ### 8.8. Variables
 572 Variables start with lower case and follow CamelCase style. Type prefixing (Systems Hungarian notation) is discouraged.
 573
 574 ✅ Good:
 575 ```cpp
 576 bool isSunYellow{true};
 577 ```
 578
 579 ❌ Bad:
 580 ```cpp
 581 bool bSunYellow{true}; // type prefixing
 582 ```
 583
 584 #### Member variables
 585 Prefix non-static member variables with `m_`. Prefix static member variables with `ms_`.
 586 ```cpp
 587 int m_variableA;
 588 static int ms_variableB;
 589 ```
 590
 591 #### Global variables
 592 Prefix global variables with `g_`
 593 ```cpp
 594 int g_globalVariableA;
 595 ```
 596 **WARNING:** Avoid use of globals as far as reasonably possible. We generally do not want to introduce new global variables.
 597
 598 **[back to top](#table-of-contents)**
 599
 600 ## 9. Comments
 601
 602 ### 9.1. General
 603
 604 Use `// ` for inline single-line and multi-line comments. Use `/* */` for the copyright comment at the beginning of the file. SPDX license headers are required for all code files (see example below).
 605
 606 ✅ Good:
 607 ```cpp
 608 /*
 609  *  Copyright (C) 2005-2018 Team Kodi
 610  *  This file is part of Kodi - https://kodi.tv
 611  *
 612  *  SPDX-License-Identifier: GPL-2.0-or-later
 613  *  See LICENSES/README.md for more information.
 614  */
 615
 616 // Nice comment
 617
 618 // This can also continue for multiple lines:
 619 // I am the second line.
 620 ```
 621
 622 ❌ Bad:
 623 ```cpp
 624 /* A comment */
 625 //another comment
 626 ```
 627
 628 ### 9.2. Doxygen
 629
 630 New classes and functions are expected to have Doxygen comments describing their purpose, parameters, and behavior in the header file. However, do not describe trivialities - it only adds visual noise. Use the Qt style with exclamation mark (`/*! */`) and backslash for doxygen commands (e.g. `\brief`).
 631
 632 ✅ Good:
 633 ```cpp
 634 /*!
 635  * \brief Splits the given input string using the given delimiter into separate strings.
 636  *
 637  * If the given input string is empty, nothing will be put into the target iterator.
 638  *
 639  * \param destination the beginning of the destination range
 640  * \param input input string to be split
 641  * \param delimiter delimiter to be used to split the input string
 642  * \param maxStrings (optional) maximum number of splitted strings
 643  * \return output iterator to the element in the destination range one past the last element
 644  *         that was put there
 645  */
 646 template<typename OutputIt>
 647 static OutputIt SplitTo(OutputIt destination, const std::string& input, const std::string& delimiter, unsigned int maxStrings = 0);
 648 ```
 649
 650 ❌ Bad:
 651 ```cpp
 652 /**
 653  * @brief Function for documentation purposes (javadoc style)
 654  */
 655 void TestFunction();
 656
 657 void ReallyComplicatedFunction(); // does something really complicated
 658
 659 /*!
 660  * \brief Frobnicate a parameter
 661  * \param param parameter to frobnicate
 662  * \result frobnication result
 663  */
 664 int Frobnicate(int param);
 665 ```
 666
 667 **[back to top](#table-of-contents)**
 668
 669 ## 10. Logging
 670
 671 Use the provided logging function `CLog::Log`. Do not log to standard output or standard error using e.g. `printf` or `std::cout`.
 672
 673 The `Log` function uses the [fmt library](http://fmtlib.net/) for formatting log messages. Basically, you can use `{}` as placeholder for anything and list the parameters to insert after the message similarly to `printf`. See [here](http://fmtlib.net/latest/syntax.html) for the detailed syntax and below for an example.
 674
 675 ✅ Good:
 676 ```cpp
 677 CLog::Log(LOGDEBUG, "Window size: {}x{}", width, height);
 678 CLog::LogF(LOGERROR, "An error occurred in window \"{}\"", name); // Use helper function `CLog::LogF` to print also the name of method.
 679 ```
 680
 681 ❌ Bad:
 682 ```cpp
 683 CLog::Log(LOGWARNING, "Window size: %dx%d", width, height); // printf-style format strings are possible, but discouraged; also the message does not warrant the warning level
 684 CLog::Log(LOGERROR, "{}: An error occurred in window \"{}\"", __FUNCTION__, name); // Do not use __FUNCTION__ macro, use `CLog::LogF` instead.
 685 printf("Window size: %dx%d", width, height);
 686 std::cout << "Window size: " << width << "x" << height << std::endl;
 687 ```
 688
 689 The predefined logging levels are `DEBUG`, `INFO`, `WARNING`, `ERROR`, and `FATAL`. Use anything `INFO` and above sparingly since it will be written to the log by default. Too many messages will clutter the log and reduce visibility of important information. `DEBUG` messages are only written when debug logging is enabled.
 690
 691 ## 11. Classes
 692
 693 ### 11.1. Member visibility
 694
 695 Make class data members `private`. Think twice before using `protected` for data members and functions, as its level of encapsulation is effectively equivalent to `public`.
 696
 697 ### 11.2. Const correctness
 698
 699 Try to mark member functions of classes as `const` whenever reasonable.
 700
 701 ### 11.3. Overriding virtual functions
 702
 703 When overriding virtual functions of a base class, add the `override` keyword. Do not add the `virtual` keyword.
 704
 705 ✅ Good:
 706 ```cpp
 707 class CLogger : public ILogger
 708 {
 709 public:
 710   void Log(...) override;
 711 }
 712 ```
 713
 714 ❌ Bad:
 715 ```cpp
 716 class CLogger : public ILogger
 717 {
 718 public:
 719   virtual void Log(...) override;
 720 }
 721 ```
 722
 723 ### 11.4. Default member initialization
 724 Use default member initialization instead of initializer lists or constructor assignments whenever it makes sense.
 725 ```cpp
 726 class Foo
 727 {
 728   bool m_fooBar{false};
 729 };
 730 ```
 731
 732 ### 11.5. Destructors in interfaces
 733
 734 A class with any virtual functions should have a destructor that is either public and virtual or else protected and non-virtual (cf. [ISO C++ guidelines](http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rc-dtor-virtual)).
 735
 736 ### 11.6. Constructor Initialization Lists
 737
 738 For lines up to [line length](#line-length) everything stays on one line, excluding the braces which must be on the following lines.
 739
 740 ```cpp
 741 MyClass::CMyClass(bool argOne, int argTwo) : m_argOne(argOne), m_argTwo(argTwo)
 742 {
 743 }
 744 ```
 745
 746 For longer lines, insert a line break before the colon and/or after the comma.
 747
 748 ```cpp
 749 MyClass::CMyClass(bool argOne,
 750                   int argTwo,
 751                   const std::string& textArg,
 752                   const std::shared_ptr<CMyOtherClass>& myOtherClass)
 753   : m_argOne(argOne),
 754     m_argTwo(argTwo),
 755     m_textArg(textArg),
 756     m_myOtherClass(myOtherClass)
 757 {
 758 }
 759 ```
 760
 761 ## 12. Other conventions
 762
 763 ### 12.1. Output parameters
 764 For functions that have multiple output values, prefer using a `struct` or `tuple` return value over output parameters that use pointers or references (cf. [ISO C++ guidelines](http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-out-multi)). In general, try to avoid output parameters completely (cf. [ISO C++ guidelines](http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-out), [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html#Output_Parameters)). At the function call site, it is completely invisible that actually a reference is being passed and the value might be modified. Return semantics make it clear what is happening.
 765
 766 ### 12.2. Casts
 767 New code has to use C++ style casts and not older C style casts. When modifying existing code the developer can choose to update it to C++ style casts or leave as is. Whenever a `dynamic_cast` is used to cast to a pointer type, the result can be `nullptr` and needs to be checked accordingly.
 768
 769 ✅ Good:
 770 ```cpp
 771 char m_dataChar{...};
 772 uint8_t m_dataInt = static_cast<uint8_t>(m_dataChar);
 773 ```
 774
 775 ❌ Bad:
 776 ```cpp
 777 char m_dataChar{...};
 778 uint8_t m_dataInt = (uint8_t)m_dataChar;
 779 ```
 780
 781 ### 12.3. `NULL` vs `nullptr`
 782 Prefer the use of `nullptr` instead of `NULL`. `nullptr` is a typesafe version and as such can't be implicitly converted to `int` or anything else.
 783
 784 ### 12.4. `auto`
 785
 786 Feel free to use `auto` wherever it improves readability, without abusing it when it is not the case.
 787 - Good places are iterators or types that have multiple sub-levels in a namespace.
 788 - Bad places are code that expects a certain type that is not immediately clear from the context, or when you declare fundamental types.
 789
 790 ✅ Good:
 791 ```cpp
 792 [...]
 793 constexpr float START_POINT = 5;
 794 [...]
 795 auto i = var.begin();
 796
 797 std::vector<CSizeInt> list;
 798 for (const auto j : list)
 799 {
 800   [...]
 801 }
 802 ```
 803
 804 ❌ Bad:
 805 ```cpp
 806 [...]
 807 constexpr auto START_POINT = 5; // may cause problems due to wrong type deduced, many auto variables make reading difficult
 808 [...]
 809 std::map<std::string, std::vector<int>>::iterator i = var.begin();
 810 ```
 811
 812 ### 12.5. `for` loops
 813 Use range-based for loops wherever it makes sense. If iterators are used, see above about using `auto`.
 814 ```cpp
 815 for (const auto& : var)
 816 {
 817   [...]
 818 }
 819 ```
 820 Remove `const` if the value has to be modified. Do not use references to fundamental types that are not modified.
 821
 822 ### 12.6. Include guards
 823
 824 Use `#pragma once`.
 825
 826 ✅ Good:
 827 ```cpp
 828 #pragma once
 829 ```
 830
 831 ❌ Bad:
 832 ```cpp
 833 #ifndef SOME_FILE_H_INCLUDED
 834 #define SOME_FILE_H_INCLUDED
 835 [...]
 836 #endif
 837 ```
 838
 839 ### 12.7. Type aliases
 840
 841 Use the C++ `using` syntax when aliasing types (encouraged when it improves readability).
 842
 843 ✅ Good:
 844 ```cpp
 845 using SizeType = int;
 846 ```
 847
 848 ❌ Bad:
 849 ```cpp
 850 typedef int SizeType;
 851 ```
 852
 853 ### 12.8. `goto`
 854
 855 Usage of `goto` is discouraged.
 856
 857 ### 12.9. Macros
 858
 859 Try to avoid using C macros. In many cases, they can be easily substituted with other non-macro constructs.
 860
 861 ### 12.10. `constexpr`
 862
 863 Prefer `constexpr` over `const` for constants when possible. Try to mark functions `constexpr` when reasonable.
 864
 865 ### 12.11. `std::string` vs `std::string_view`
 866
 867 Prefer `std::string_view` over `std::string` when reasonable. Good examples are constants or method arguments. In the latter case, it is not required to declare the argument as reference or const, since the data source of string views are immutable by definition. A bad example is when you need a NUL-terminated C string, e.g. to interact with a C API. `std::string_view` does not offer a `c_str()` function like `std::string` does, but if you do not need a C string you can use `data()` to get the raw source of the data.
 868
 869 Main reasons why we prefer `std::string_view` are: execution performance, no memory allocations, substrings can be made without copy, and the possibility to reuse the same data without reallocation.
 870
 871 Avoid using `std::string_view` when you are not sure where the source of data is allocated, or as return value of a method. If not handled properly, the source (storage) of the data may go out of scope. As a consequence, the program enters undefined behavior and may crash, behave strangely, or introduce potential security issues.
 872
 873 ✅ Good:
 874 ```cpp
 875 namespace
 876 {
 877 constexpr std::string_view CONSTANT_FOO{"foo-bar"};
 878 } // unnamed namespace
 879
 880 void CClass::SetText(std::string_view value)
 881 {
 882   CLog::LogF(LOGDEBUG, "My name is {}", value);
 883 }
 884
 885 [...]
 886 SetText(CONSTANT_FOO.substr(0, 3)); // substr returns a modified view of the same string_view, thus without allocations
 887 ```
 888
 889 ❌ Bad:
 890 ```cpp
 891 namespace
 892 {
 893 constexpr std::string CONSTANT_FOO{"foo-bar"}; // using string_view will avoid a memory allocation
 894 } // unnamed namespace
 895
 896 void CClass::SetText(const std::string& value) // despite being declared as a reference, using string_view will result in a lower overhead in many cases (e.g., when passing a C string literal)
 897 {
 898   CLog::LogF(LOGDEBUG, "My name is {}", value);
 899 }
 900
 901 [...]
 902 SetText(CONSTANT_FOO.substr(0, 3)); // using string_view will avoid a memory allocation due to substr
 903 ```
 904
 905 **[back to top](#table-of-contents)**