doc/coding.txt

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