doc/coding.md

   1 Coding
   2 ====================
   3
   4 Various coding styles have been used during the history of the codebase,
   5 and the result is not very consistent. However, we're now trying to converge to
   6 a single style, so please use it in new code. Old code will be converted
   7 gradually.
   8 - Basic rules specified in src/.clang-format. Use a recent clang-format-3.5 to format automatically.
   9   - Braces on new lines for namespaces, classes, functions, methods.
  10   - Braces on the same line for everything else.
  11   - 4 space indentation (no tabs) for every block except namespaces.
  12   - No indentation for public/protected/private or for namespaces.
  13   - No extra spaces inside parenthesis; don't do ( this )
  14   - No space after function names; one space after if, for and while.
  15
  16 Block style example:
  17 ```c++
  18 namespace foo
  19 {
  20 class Class
  21 {
  22     bool Function(char* psz, int n)
  23     {
  24         // Comment summarising what this section of code does
  25         for (int i = 0; i < n; i++) {
  26             // When something fails, return early
  27             if (!Something())
  28                 return false;
  29             ...
  30         }
  31
  32         // Success return is usually at the end
  33         return true;
  34     }
  35 }
  36 }
  37 ```
  38
  39 Doxygen comments
  40 -----------------
  41
  42 To facilitate the generation of documentation, use doxygen-compatible comment blocks for functions, methods and fields.
  43
  44 For example, to describe a function use:
  45 ```c++
  46 /**
  47  * ... text ...
  48  * @param[in] arg1    A description
  49  * @param[in] arg2    Another argument description
  50  * @pre Precondition for function...
  51  */
  52 bool function(int arg1, const char *arg2)
  53 ```
  54 A complete list of `@xxx` commands can be found at http://www.stack.nl/~dimitri/doxygen/manual/commands.html.
  55 As Doxygen recognizes the comments by the delimiters (`/**` and `*/` in this case), you don't
  56 *need* to provide any commands for a comment to be valid, just a description text is fine.
  57
  58 To describe a class use the same construct above the class definition:
  59 ```c++
  60 /**
  61  * Alerts are for notifying old versions if they become too obsolete and
  62  * need to upgrade. The message is displayed in the status bar.
  63  * @see GetWarnings()
  64  */
  65 class CAlert
  66 {
  67 ```
  68
  69 To describe a member or variable use:
  70 ```c++
  71 int var; //!< Detailed description after the member
  72 ```
  73
  74 Also OK:
  75 ```c++
  76 ///
  77 /// ... text ...
  78 ///
  79 bool function2(int arg1, const char *arg2)
  80 ```
  81
  82 Not OK (used plenty in the current source, but not picked up):
  83 ```c++
  84 //
  85 // ... text ...
  86 //
  87 ```
  88
  89 A full list of comment syntaxes picked up by doxygen can be found at http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html,
  90 but if possible use one of the above styles.
  91
  92 Locking/mutex usage notes
  93 -------------------------
  94
  95 The code is multi-threaded, and uses mutexes and the
  96 LOCK/TRY_LOCK macros to protect data structures.
  97
  98 Deadlocks due to inconsistent lock ordering (thread 1 locks cs_main
  99 and then cs_wallet, while thread 2 locks them in the opposite order:
 100 result, deadlock as each waits for the other to release its lock) are
 101 a problem. Compile with -DDEBUG_LOCKORDER to get lock order
 102 inconsistencies reported in the debug.log file.
 103
 104 Re-architecting the core code so there are better-defined interfaces
 105 between the various components is a goal, with any necessary locking
 106 done by the components (e.g. see the self-contained CKeyStore class
 107 and its cs_KeyStore lock for example).
 108
 109 Threads
 110 -------
 111
 112 - ThreadScriptCheck : Verifies block scripts.
 113
 114 - ThreadImport : Loads blocks from blk*.dat files or bootstrap.dat.
 115
 116 - StartNode : Starts other threads.
 117
 118 - ThreadDNSAddressSeed : Loads addresses of peers from the DNS.
 119
 120 - ThreadMapPort : Universal plug-and-play startup/shutdown
 121
 122 - ThreadSocketHandler : Sends/Receives data from peers on port 8333.
 123
 124 - ThreadOpenAddedConnections : Opens network connections to added nodes.
 125
 126 - ThreadOpenConnections : Initiates new connections to peers.
 127
 128 - ThreadMessageHandler : Higher-level message handling (sending and receiving).
 129
 130 - DumpAddresses : Dumps IP addresses of nodes to peers.dat.
 131
 132 - ThreadFlushWalletDB : Close the wallet.dat file if it hasn't been used in 500ms.
 133
 134 - ThreadRPCServer : Remote procedure call handler, listens on port 8332 for connections and services them.
 135
 136 - BitcoinMiner : Generates bitcoins (if wallet is enabled).
 137
 138 - Shutdown : Does an orderly shutdown of everything.