doc/coding.txt

   1 Please be consistent with the existing coding style.\r
   2 \r
   3 Block style:\r
   4 \r
   5 bool Function(char* psz, int n)\r
   6 {\r
   7     // Comment summarising what this section of code does\r
   8     for (int i = 0; i < n; i++)\r
   9     {\r
  10         // When something fails, return early\r
  11         if (!Something())\r
  12             return false;\r
  13         ...\r
  14     }\r
  15 \r
  16     // Success return is usually at the end\r
  17     return true;\r
  18 }\r
  19 \r
  20 - ANSI/Allman block style\r
  21 - 4 space indenting, no tabs\r
  22 - No extra spaces inside parenthesis; please don't do ( this )\r
  23 - No space after function names, one space after if, for and while\r
  24 \r
  25 Variable names begin with the type in lowercase, like nSomeVariable.\r
  26 Please don't put the first word of the variable name in lowercase like\r
  27 someVariable.\r
  28 \r
  29 Common types:\r
  30 n       integer number: short, unsigned short, int, unsigned int,\r
  31             int64, uint64, sometimes char if used as a number\r
  32 d       double, float\r
  33 f       flag\r
  34 hash    uint256\r
  35 p       pointer or array, one p for each level of indirection\r
  36 psz     pointer to null terminated string\r
  37 str     string object\r
  38 v       vector or similar list objects\r
  39 map     map or multimap\r
  40 set     set or multiset\r
  41 bn      CBigNum\r
  42 \r
  43 -------------------------\r
  44 Locking/mutex usage notes\r
  45 \r
  46 The code is multi-threaded, and uses mutexes and the\r
  47 CRITICAL_BLOCK/TRY_CRITICAL_BLOCK macros to protect data structures.\r
  48 \r
  49 Deadlocks due to inconsistent lock ordering (thread 1 locks cs_main\r
  50 and then cs_wallet, while thread 2 locks them in the opposite order:\r
  51 result, deadlock as each waits for the other to release its lock) are\r
  52 a problem. Compile with -DDEBUG_LOCKORDER to get lock order\r
  53 inconsistencies reported in the debug.log file.\r
  54 \r
  55 Re-architecting the core code so there are better-defined interfaces\r
  56 between the various components is a goal, with any necessary locking\r
  57 done by the components (e.g. see the self-contained CKeyStore class\r
  58 and its cs_KeyStore lock for example).\r
  59 \r
  60 -------\r
  61 Threads\r
  62 \r
  63 StartNode : Starts other threads.\r
  64 \r
  65 ThreadGetMyExternalIP : Determines outside-the-firewall IP address,\r
  66 sends addr message to connected peers when it determines it. \r
  67 \r
  68 ThreadIRCSeed : Joins IRC bootstrapping channel, watching for new\r
  69 peers and advertising this node's IP address. \r
  70 \r
  71 ThreadSocketHandler : Sends/Receives data from peers on port 8333.\r
  72 \r
  73 ThreadMessageHandler : Higher-level message handling (sending and\r
  74 receiving).\r
  75 \r
  76 ThreadOpenConnections : Initiates new connections to peers.\r
  77 \r
  78 ThreadTopUpKeyPool : replenishes the keystore's keypool.\r
  79 \r
  80 ThreadCleanWalletPassphrase : re-locks an encrypted wallet after user\r
  81 has unlocked it for a period of time. \r
  82 \r
  83 SendingDialogStartTransfer : used by pay-via-ip-address code (obsolete)\r
  84 \r
  85 ThreadDelayedRepaint : repaint the gui \r
  86 \r
  87 ThreadFlushWalletDB : Close the wallet.dat file if it hasn't been used\r
  88 in 500ms.\r
  89 \r
  90 ThreadRPCServer : Remote procedure call handler, listens on port 8332\r
  91 for connections and services them.\r
  92 \r
  93 ThreadBitcoinMiner : Generates bitcoins\r
  94 \r
  95 ThreadMapPort : Universal plug-and-play startup/shutdown\r
  96 \r
  97 Shutdown : Does an orderly shutdown of everything\r
  98 \r
  99 ExitTimeout : Windows-only, sleeps 5 seconds then exits application\r