CODING_GUIDELINES.md

   1 # Coding Guidelines
   2
   3 All new code **must** follow the following coding guidelines. \
   4 If you make changes in a file that still uses another coding style, make sure that you follow these guidelines for your changes. \
   5 For programming languages other than C++ (e.g. JavaScript) used in this repository and submodules, unless otherwise specified, coding guidelines listed here applies as much as possible.
   6
   7 **Note 1:** I will not take your head if you forget and use another style. However, most probably the request will be delayed until you fix your coding style. \
   8 **Note 2:** You can use the `uncrustify` program/tool to clean up any source file. Use it with the `uncrustify.cfg` configuration file found in the root folder. \
   9 **Note 3:** There is also a style for QtCreator but it doesn't cover all cases. In QtCreator `Tools->Options...->C++->Code Style->Import...` and choose the `codingStyleQtCreator.xml` file found in the root folder.
  10
  11 ## Table Of Contents
  12
  13 * [1. New lines &amp; curly braces](#1-new-lines--curly-braces)
  14   * [a. Function blocks, class/struct definitions, namespaces](#a-function-blocks-classstruct-definitions-namespaces)
  15   * [b. Other code blocks](#b-other-code-blocks)
  16   * [c. Blocks in switch's case labels](#c-blocks-in-switchs-case-labels)
  17   * [d. If-else statements](#d-if-else-statements)
  18   * [e. Single statement if blocks](#e-single-statement-if-blocks)
  19   * [f. Acceptable conditions to omit braces](#f-acceptable-conditions-to-omit-braces)
  20   * [g. Brace enclosed initializers](#g-brace-enclosed-initializers)
  21 * [2. Indentation](#2-indentation)
  22 * [3. File encoding and line endings](#3-file-encoding-and-line-endings)
  23 * [4. Initialization lists](#4-initialization-lists)
  24 * [5. Enums](#5-enums)
  25 * [6. Names](#6-names)
  26   * [a. Type names and namespaces](#a-type-names-and-namespaces)
  27   * [b. Variable names](#b-variable-names)
  28   * [c. Private member variable names](#c-private-member-variable-names)
  29 * [7. Header inclusion order](#7-header-inclusion-order)
  30 * [8. Include guard](#8-include-guard)
  31 * [9. Misc](#9-misc)
  32 * [10. Git commit message](#10-git-commit-message)
  33 * [11. Not covered above](#11-not-covered-above)
  34
  35 ---
  36
  37 ## 1. New lines & curly braces
  38
  39 ### a. Function blocks, class/struct definitions, namespaces
  40
  41 ```c++
  42 int myFunction(int a)
  43 {
  44     // code
  45 }
  46
  47 void myFunction() {} // empty body
  48
  49 MyClass::MyClass(int *parent)
  50     : m_parent {parent}
  51 {
  52     // initialize
  53 }
  54
  55 int MyClass::myMethod(int a)
  56 {
  57     // code
  58 }
  59
  60 class MyOtherClass
  61 {
  62 public:
  63     // code
  64
  65 protected:
  66     // code
  67
  68 private:
  69     // code
  70 };
  71
  72 namespace Name
  73 {
  74     // code
  75 }
  76
  77 // Lambdas
  78 [](int arg1, int arg2) -> bool { return arg1 < arg2; }
  79
  80 [this](int arg)
  81 {
  82     this->acc += arg;
  83 }
  84 ```
  85
  86 ### b. Other code blocks
  87
  88 ```c++
  89 if (condition)
  90 {
  91     // code
  92 }
  93
  94 for (int a = 0; a < b; ++b)
  95 {
  96     // code
  97 }
  98
  99 switch (a)
 100 {
 101 case 1:
 102     // blah
 103 case 2:
 104     // blah
 105 default:
 106     // blah
 107 }
 108
 109 {
 110     // code
 111 }
 112 ```
 113
 114 ### c. Blocks in switch's case labels
 115
 116 ```c++
 117 switch (var)
 118 {
 119 case 1:
 120     {
 121         // declare local variables
 122         // code
 123     }
 124     break;
 125 case 2:
 126     {
 127         // declare local variables
 128         // code
 129     }
 130     break;
 131 default:
 132     // code
 133 }
 134 ```
 135
 136 ### d. If-else statements
 137
 138 The `else if`/`else` must be on their own lines:
 139
 140 ```c++
 141 if (condition)
 142 {
 143     // code
 144 }
 145 else if (condition)
 146 {
 147     // code
 148 }
 149 else
 150 {
 151     // code
 152 }
 153 ```
 154
 155 ### e. Single statement if blocks
 156
 157 Most single statement if blocks should look like this:
 158
 159 ```c++
 160 if (condition)
 161     a = a + b;
 162 ```
 163
 164 One acceptable exception to this can be `return`, `break` or `continue` statements,
 165 provided that the test condition isn't very long and its body statement occupies only one line.
 166 However you can still choose to use the first rule.
 167
 168 ```c++
 169 if (a > 0) return;
 170
 171 while (p)
 172 {
 173     // ...
 174     if (!b) continue;
 175 }
 176 ```
 177
 178 ### f. Acceptable conditions to omit braces
 179
 180 When the conditional statement in `if`/`else` has only one line and its body occupy only one line,
 181 this also applies to loops statements. \
 182 Notice that for a series of `if - else` branches, if one branch needs braces then all branches must add braces.
 183
 184 ```c++
 185 if (a < b)  // conditional statement
 186     do(a);  // body
 187
 188 if (a < b)
 189     do(a);
 190 else if (a > b)
 191     do(b);
 192 else
 193     do(c);
 194
 195 if (a < b)
 196 {
 197     do(a);
 198 }
 199 else if (a > b)
 200 {
 201     // curly braces required here, then all branches should also add them
 202     do(b);
 203     do(d);
 204 }
 205 else
 206 {
 207     do(c);
 208 }
 209 ```
 210
 211 ### g. Brace enclosed initializers
 212
 213 Unlike single-line functions, you must not insert spaces between the brackets and concluded expressions. \
 214 But you must insert a space between the variable name and initializer.
 215
 216 ```c++
 217 Class obj {}; // empty
 218 Class obj {expr};
 219 Class obj {expr1, /*...,*/ exprN};
 220 QVariantMap map {{"key1", 5}, {"key2", 10}};
 221 ```
 222
 223 ## 2. Indentation
 224
 225 4 spaces.
 226
 227 ## 3. File encoding and line endings
 228
 229 UTF-8 and Unix-like line ending (LF). Unless some platform specific files need other encodings/line endings.
 230
 231 ## 4. Initialization lists
 232
 233 Initialization lists should be vertical. This will allow for more easily readable diffs. The initialization colon should be indented and in its own line along with first argument. The rest of the arguments should be indented too and have the comma prepended.
 234
 235 ```c++
 236 myClass::myClass(int a, int b, int c, int d)
 237     : m_a {a}
 238     , m_b {b}
 239     , m_c {c}
 240     , m_d {d}
 241 {
 242     // code
 243 }
 244 ```
 245
 246 ## 5. Enums
 247
 248 Enums should be vertical. This will allow for more easily readable diffs. The members should be indented.
 249
 250 ```c++
 251 enum Days
 252 {
 253     Monday,
 254     Tuesday,
 255     Wednesday,
 256     Thursday,
 257     Friday,
 258     Saturday,
 259     Sunday
 260 };
 261 ```
 262
 263 ## 6. Names
 264
 265 All names should be camelCased.
 266
 267 ### a. Type names and namespaces
 268
 269 Type names and namespaces start with Upper case letter (except POD types).
 270
 271 ```c++
 272 class ClassName {};
 273
 274 struct StructName {};
 275
 276 enum EnumName {};
 277
 278 typedef QList<ClassName> SomeList;
 279
 280 namespace NamespaceName
 281 {
 282 }
 283 ```
 284
 285 ### b. Variable names
 286
 287 Variable names start with lower case letter.
 288
 289 ```c++
 290 int myVar;
 291 ```
 292
 293 ### c. Private member variable names
 294
 295 Private member variable names start with lower case letter and should have ```m_``` prefix.
 296
 297 ```c++
 298 class MyClass
 299 {
 300     int m_myVar;
 301 }
 302 ```
 303
 304 ## 7. Header inclusion order
 305
 306 The headers should be placed in the following group order:
 307
 308 1. Module header (in .cpp)
 309 2. C++ Standard Library headers
 310 3. System headers
 311 4. Boost library headers
 312 5. Libtorrent headers
 313 6. Qt headers
 314 7. qBittorrent's own headers, starting from the *base* headers.
 315
 316 The headers should be ordered alphabetically within each group. \
 317 If there are conditionals for the same header group, then put them at the bottom of the respective group. \
 318 If there are conditionals that contain headers from several different header groups, then put them above the "qBittorrent's own headers" group.
 319
 320 One exception is the header containing the library version (for example, QtGlobal), this particular header isn't constrained by the aforementioned order.
 321
 322 Example:
 323
 324 ```c++
 325 // file: examplewidget.cpp
 326
 327 // Module header
 328 #include "examplewidget.h"
 329
 330 // exceptions, headers containing version number
 331 #include <boost/version.hpp>
 332 #include <libtorrent/version.hpp>
 333 #include <QtGlobal>
 334
 335 // C++ Standard Library headers
 336 #include <cstdio>
 337
 338 #ifdef Q_OS_WIN  // conditional
 339 #include <cmath>
 340 #endif
 341
 342 // System headers
 343 #ifdef Q_OS_WIN
 344 #include <Windows.h>
 345 #endif
 346
 347 // Boost library headers
 348 #include <boost/circular_buffer.hpp>
 349
 350 // Libtorrent headers
 351 #include <libtorrent/session.hpp>
 352
 353 // Qt headers
 354 #include <QString>
 355 #include <QUrl>
 356
 357 #ifdef Q_OS_MACOS  // conditional
 358 #include <QFont>
 359 #endif
 360
 361 // conditional that contains headers from several different header groups
 362 #if LIBTORRENT_VERSION_NUM >= 10100
 363 #include <memory>
 364 #include <QElapsedTimer>
 365 #endif
 366
 367 // qBittorrent's own headers
 368 #include "base/bittorrent/infohash.h"
 369 #include "anothermodule.h"
 370 #include "ui_examplewidget.h"
 371 ```
 372
 373 ## 8. Include guard
 374
 375 `#pragma once` must be used instead of a "classic include guard":
 376
 377 ```c++
 378 // examplewidget.h
 379
 380 #pragma once
 381
 382 #include <QWidget>
 383
 384 class ExampleWidget : public QWidget
 385 {
 386     // (some code omitted)
 387 };
 388
 389 ```
 390
 391 ## 9. Misc
 392
 393 * Line breaks for long lines with operation:
 394
 395   ```c++
 396   a += "b"
 397     + "c"
 398     + "d";
 399   ```
 400
 401 * **auto** keyword
 402
 403   We allow the use of the **auto** keyword only where it is strictly necessary (for example, to declare a lambda object, etc.), or where it **enhances** the readability of the code. \
 404   Declarations for which one can gather enough information about the object interface (type) from its name or the usage pattern (an iterator or a loop variable are good examples of clear patterns) or the right part of the expression nicely fit here.
 405
 406   When weighing whether to use an auto-typed variable please think about potential reviewers of your code, who will read it as a plain diff (on github.com, for instance). \
 407   Please make sure that such reviewers can understand the code completely and without excessive effort.
 408
 409   Some valid use cases:
 410
 411   * Container iteration and casts:
 412
 413     ```c++
 414     template <typename List>
 415     void doSomethingWithList(const List &list)
 416     {
 417         foreach (const auto &item, list)
 418         {
 419             // we don't know item type here so we use 'auto' keyword
 420             // do something with item
 421         }
 422     }
 423
 424     for (auto it = container.begin(), end = container.end(); it != end; ++it)
 425     {
 426         // we don't need to know the exact iterator type,
 427         // because all iterators have the same interface
 428     }
 429
 430     auto spinBox = static_cast<QSpinBox*>(sender());
 431     // we know the variable type based on the right-hand expression
 432     ```
 433
 434   * Notice the spaces in the following specific situations:
 435
 436     ```c++
 437     // Before and after the assignment and other binary (and ternary) operators there should be a space
 438     // There should not be a space between increment/decrement and its operand
 439     a += 20;
 440     a = (b <= MAX_B ? b : MAX_B);
 441     ++a;
 442     --b;
 443     for (int a = 0; a < b; ++b)
 444     {
 445     }
 446     // Range-based for loop, spaces before and after the colon
 447     for (auto i : container)
 448     {
 449     }
 450     // Derived class, spaces before and after the colon
 451     class Derived : public Base
 452     {
 453     };
 454     ```
 455
 456 * Prefer pre-increment, pre-decrement operators
 457
 458   ```c++
 459   ++i, --j;  // Yes
 460   i++, j--;  // No
 461   ```
 462
 463 * private/public/protected must not be indented
 464
 465 * Preprocessor commands must go at line start
 466
 467 * Method definitions aren't allowed in header files
 468
 469 ## 10. Git commit message
 470
 471 1. Limit the subject line to 50 characters. Subject should contain only the very essence of the changes (you should avoid extra details and internals)
 472 2. Separate subject from body with a blank line
 473 3. Capitalize the subject line
 474 4. Do not end the subject line with a period
 475 5. Use the imperative mood in the subject line (it's like you're ordering the program to do something (e.g. "Don't create temporary substrings")
 476 6. Wrap the body at 72 characters
 477 7. Use the body to explain what and why vs. how
 478 8. If commit fixes a reported issue, mention it in the message body (e.g. `Closes #4134.`)
 479
 480 ## 11. Not covered above
 481
 482 If something isn't covered above, just follow the same style the file you are editing has. \
 483 *This guide is not exhaustive and the style for a particular piece of code not specified here will be determined by project members on code review.*